API¶
-
class
cotyledon.
Service
(worker_id)¶ Base class for a service
This class will be executed in a new child process/worker
ServiceWorker
of aServiceManager
. It registers signals to manager the reloading and the ending of the process.Methods
run()
,terminate()
andreload()
are optional.-
__init__
(worker_id)¶ Create a new Service
Parameters: worker_id (int) – the identifier of this service instance The identifier of the worker can be used for workload repartition because it’s consistent and always the same.
For example, if the number of workers for this service is 3, one will got 0, the second got 1 and the last got 2. if worker_id 1 died, the new spawned process will got 1 again.
-
graceful_shutdown_timeout
= None¶ Timeout after which a gracefully shutdown service will exit. zero means endless wait. None means same as ServiceManager that launch the service
-
name
= None¶ Service name used in the process title and the log messages in additionnal of the worker_id.
-
reload
()¶ Reloading of the service
This method will be executed when the Service receives a SIGHUP.
If not implemented the process will just end with status 0 and
ServiceRunner
will start a new fresh process for this service with the same worker_id.Any exceptions raised by this method will be logged and the worker will exit with status 1.
-
run
()¶ Method representing the service activity
If not implemented the process will just wait to receive an ending signal.
This method is ran into the thread and can block or return as needed
Any exceptions raised by this method will be logged and the worker will exit with status 1.
-
terminate
()¶ Gracefully shutdown the service
This method will be executed when the Service has to shutdown cleanly.
If not implemented the process will just end with status 0.
To customize the exit code, the
SystemExit
exception can be used.Any exceptions raised by this method will be logged and the worker will exit with status 1.
-
-
class
cotyledon.
ServiceManager
(wait_interval=0.01, graceful_shutdown_timeout=60)¶ Manage lifetimes of services
ServiceManager
acts as a master process that controls the lifetime of children processes and restart them if they die unexpectedly. It also propagate some signals (SIGTERM, SIGALRM, SIGINT and SIGHUP) to them.Each child process (
ServiceWorker
) runs an instance of aService
.An application must create only one
ServiceManager
class and useServiceManager.run()
as main loop of the application.Usage:
class MyService(Service): def __init__(self, worker_id, myconf): super(MyService, self).__init__(worker_id) preparing_my_job(myconf) self.running = True def run(self): while self.running: do_my_job() def terminate(self): self.running = False gracefully_stop_my_jobs() def reload(self): restart_my_job() class MyManager(ServiceManager): def __init__(self): super(MyManager, self).__init__() self.register_hooks(on_reload=self.reload) conf = {'foobar': 2} self.service_id = self.add(MyService, 5, conf) def reload(self): self.reconfigure(self.service_id, 10) MyManager().run()
This will create 5 children processes running the service MyService.
-
__init__
(wait_interval=0.01, graceful_shutdown_timeout=60)¶ Creates the ServiceManager object
Parameters: wait_interval (float) – time between each new process spawn
-
add
(service, workers=1, args=None, kwargs=None)¶ Add a new service to the ServiceManager
Parameters: - service (callable) – callable that return an instance of
Service
- workers (int) – number of processes/workers for this service
- args (tuple) – additional positional arguments for this service
- kwargs (dict) – additional keywoard arguments for this service
Returns: a service id
Return type: uuid.uuid4
- service (callable) – callable that return an instance of
-
reconfigure
(service_id, workers)¶ Reconfigure a service registered in ServiceManager
Parameters: - service_id (uuid.uuid4) – the service id
- workers (int) – number of processes/workers for this service
Raises: ValueError
-
register_hooks
(on_terminate=None, on_reload=None, on_new_worker=None, on_dead_worker=None)¶ Register hook methods
This can be callable multiple times to add more hooks, hooks are executed in added order. If a hook raised an exception, next hooks will be not executed.
Parameters: - on_terminate (callable()) – method called on SIGTERM
- on_reload (callable()) – method called on SIGHUP
- on_new_worker (callable(service_id, worker_id, exit_code)) – method called in the child process when this one is ready
- on_new_worker – method called when a child died
If window support is planned, hooks callable must support to be pickle.pickle(). See CPython multiprocessing module documentation for more detail.
-
run
()¶ Start and supervise services workers
This method will start and supervise all children processes until the master process asked to shutdown by a SIGTERM.
All spawned processes are part of the same unix process group.
-