Sunday, 6 July 2025
@pabarino:matrix.orgA Temporary Solution for Job Tracking
This week, I revisited the KUiServerJobTracker issue in the PIM Migration Agent. After last week’s D-Bus debugging and architectural cleanup, it became clear that replacing it entirely was more complex than initially expected.
After discussing with my mentor Carl, he summarized the situation in an email to the KDE PIM mailing list. In it, he outlined the limitations we were facing:
“The agent relies on KUiServerJobTracker, which aside from requiring a port to KUiServerV2JobTracker, also has the issue that it links to QtWidgets while not using QWidget itself.”
The email resulted in feedback from Volker Krause. In his response he agreed with one of Carl’s suggestion that I ultimately pursued: rather than remove the job tracker altogether or build an entirely new progress infrastructure, I created a local copy of KUiServerV2JobTracker inside the kdepim-runtime repository and carefully stripped out its QtWidgets linkage.
This forked version is temporary and self-contained, with a clear path to removal once the upstream KDE Frameworks address the QtWidgets dependency—likely by KF7. It allowed me to retain proper system tray integration for job tracking (which AgentBase’s built-in D-Bus support cannot currently provide), while still meeting the goal of removing QtWidgets from the Migration Agent’s core.
Shedding the Final Dependencies
With the tracker replaced, I focused on removing the last traces of QtWidgets from the Migration Agent. This included cleaning up the custom D-Bus interface and eliminating now-redundant methods. The final dependencies were located in individual subcomponent CMakeLists.txt files, which were still linking against QtWidgets.
After updating those, the result is a fully decoupled agent:
The PIM Migration Agent’s core logic is now completely free of QtWidgets.
In addition, I integrated the manual migration tasks into the job executor, allowing them to report progress using the same job tracking mechanisms as the automated tasks.
A New Akonadi Capability: SingleShot Agents
The mailing list discussion also highlighted another inefficiency: the Migration Agent doesn’t need to run persistently. As Volker suggested:
“Keep it as an agent but give it a special ‘SingleShot’ flag… with Akonadi shutting it down again automatically once done.”
Building on this idea, I introduced a new Akonadi capability: SingleShot agents. This lets agents perform their work once and automatically exit afterward, conserving system resources.
The mechanism works as follows:
An agent declares
X-Akonadi-Capabilities=SingleShotin its.desktopfile.When launched, the agent does its work.
Once finished, it emits a new
finished()D-Bus signal.The Akonadi manager listens for this signal and terminates the agent process.
This pattern fits well with agents like the Migration Agent that don’t need to remain active beyond their immediate tasks.
Current Status and What’s Next
Draft merge requests for both akonadi and kdepim-runtime are already open to gather feedback on the SingleShot capability and the updated job tracking approach.
The only remaining issue is that the finished() signal doesn’t seem to shut down the agent as expected when testing through akonadiconsole. Debugging this signal propagation is my focus for the upcoming week. Once resolved, the agent will fully behave as a lightweight, on-demand component.
This week’s changes not only complete the agent’s QtWidgets decoupling but also introduce a meaningful architectural improvement to Akonadi itself—one that may benefit other agents in the future.
TSDgeos
