Plugin Authors

For plugin authors

JobCockpit keeps Enigma2's own job classes (Job, Task and the others of Components.Task) and adds to them. A plugin that already creates Job objects needs only a few lines to get its own job manager, to have its jobs kept after they end, and to open the job screen for them.

Registering a job manager

JobSupervisor holds one job manager for each plugin. Ask it for yours with a short id, for example the id of your plugin:

from Components.Task import Job
from Plugins.SystemPlugins.JobCockpit.JobSupervisor import JobSupervisor

job_manager = JobSupervisor.getInstance().getJobManager("MYP")

The manager is created when it is asked for the first time, and the same one is returned every time after that.

• Every manager runs one job at a time and queues the others, in the order they were added. Managers run independently of each other, so the jobs of two plugins run in parallel.
• The id "DEFAULT" is the job manager of Enigma2 itself (the one used by the AutoTimer, the package manager and others). You do not have to use it.

Adding a job

job = Job("Download: My Movie")
job.keep = True          # keep the job in the list after it has ended
MyTask(job, ...)         # a Task of Components.Task: it does the work
job_manager.AddJob(job)  # starts it now, or queues it behind the running one

job.keep = True is what makes JobCockpit remember the job. A finished job goes to the list of successful jobs and a failed one to the list of failed jobs, until the user cleans them up. Without keep the job is forgotten when it ends, as with the original job manager.

The name of the job is the first line of its entry in the list, so make it tell what the job does. The state and the progress (job.getProgress()) are shown under it. The states are Job.NOT_STARTED, Job.IN_PROGRESS, Job.FINISHED and Job.FAILED.

Querying the jobs

JobSupervisor returns the jobs of one plugin, or of all plugins when no id is given:

supervisor = JobSupervisor.getInstance()

supervisor.getPendingJobs("MYP")      # running and waiting
supervisor.getFailedJobs("MYP")       # failed (only jobs with keep)
supervisor.getSuccessfulJobs("MYP")   # finished (only jobs with keep)
supervisor.getPendingJobs()           # of all plugins
supervisor.getPendingJobs("MYP", as_tuples=True)   # a list of (plugin id, job)

The Cockpit plugins share a small helper, JobUtils.py:

Function	Result
getPendingJobs(plugin_id="", as_tuples=False)	The running and waiting jobs
getPendingJob(plugin_id, path)	The pending job whose target_path is path, or None. A plugin that sets job.target_path (for example the path of a file it writes) can find out whether a file is still being written.

A job manager can also be used directly:

Method	Does
AddJob(job)	Adds a job and starts it if none is running
AbortJob(job, force=False)	Aborts a running job. With force the resident tasks of the job are aborted as well
RemoveJob(job)	Removes a waiting, a finished or a failed job from its list
CleanupJobs()	Clears the lists of finished and failed jobs

JobCockpit.abortJob(job, plugin_id, force=True) is a static helper that aborts a job if it is running.

Opening the job screen

JobCockpit is registered as a plugin of the type WHERE_JOBCOCKPIT (a number defined in PluginUtils.py, which the Cockpit plugins share). Open the screen for the jobs of your plugin like this:

from .PluginUtils import WHERE_JOBCOCKPIT, getPlugin

plugin = getPlugin(WHERE_JOBCOCKPIT)   # None if JobCockpit is not installed
if plugin:
    plugin(session, "MYP")             # only the jobs of "MYP"

With an empty id, or from the plugin menu, the screen shows the jobs of all plugins. See the User Guide for what the user can do there.

Notes

• A plugin that depends on JobCockpit lists enigma2-plugin-systemplugins-jobcockpit in its CONTROL/control. If JobCockpit is optional for you, import it in a try block and use Components.Task.job_manager otherwise.
• JobCockpit replaces Components/Task.py of Enigma2 when it is installed (see the User Guide). Job, Task and the other classes are the original ones, extended by the lists of finished and failed jobs, so a plugin that does not know JobCockpit works as before.