Worker

Worker

The worker enables dispatching jobs to an external process. Here some use cases:

• immediate job: email sending in outside the RPC request, because it would block the request for too long.
• scheduled job: remove a temporary file after 2 days after creating it.
• recurring job: let a resource manager check for expired slivers on a regular basis.

When adding jobs to the worker, the descriptions are saved to a database. In order for these jobs to be executed the worker server needs to be started. So, if any plugin in you setup needs job processing, please start the ./main.py --worker process.

The location of the database can be configured via the configuration client. The relevant key is named: worker.dbpath. The path specified can be relative to AMsoil's root folder or an absolute path (default: deploy/worker.db).

After starting the server, please check AMsoil's log regularly.

Developing with the worker

When developing plugins, you can use the worker's job processing like so (add the dependency to the MANIFEST.json):

    worker = pm.getService('worker')
    # run as soon as possible
    worker.add("myservice", "mymethod", "parameter1")
    # run every minute
    worker.addAsReccurring("myservice", "mymethod", [1,2,3], 60)
    # run in 2 hours
    worker.addAsScheduled("myservice", "mymethod", None, datetime.now() + timedelta(0, 60*60*2))

In the example the worker server will lookup myservice via the plugin manager and then call job method mymethod. The parameters given in the add...-method are serialized with pickle. They will be deserialized and given to the job method is executed. Please note that the worker server is a different process than the RPC server.
Do not perform long-working tasks in the job method. The worker server will wait for the job method to complete and only then continue with other jobs.

The mymethod must fulfill the following characteristics:

• be callable,
• take exactly one parameter (and self if the given service is a class)
• be decorated with the @worker.outsideprocess annotation.

    worker = pm.getService('worker')
    class MyService(object):
        # ...
        @worker.outsideprocess
        def mymethod(self, params):
            # do stuff
            pass 

Exceptions in the job method will be written to the log.

For detailed usage please read the API documentation in the plugin.

Pitfalls

• You need to restart the worker server after changes to the code (even in in your plugin).
• Long-working jobs block the execution of other jobs.
• The execution time of a job is not guaranteed. They might be executed later than desired, but not before.
• The job method is called in a different process in a different context. So be sure to use only persistant data via a database or similar.
• When adding jobs during initialization of your plugin, it might happen, that your job method will be called twice. Write the method so it can manage duplicate executions.
• It is not possible to add two recurring jobs with the same signature (signature is "service_name+callable_attr_str")
• If you once added a recurring job, even if you do not add it again during AMsoil's bootstrap, it will still be in the database and hence executed (In this case it is safe to remove the database, e.g. rm deploy/worker.db).