acme.helpers.BackgroundWorker.BackgroundWorkerPool

class documentation

class BackgroundWorkerPool(object):

Constructor: BackgroundWorkerPool(*args, **kwargs)

Pool and factory for background workers and actors.

Class Method	`countJobs`	Return the number of running and paused Jobs.
Class Method	`findWorkers`	Find and return a list of worker(s) that match the search criteria.
Class Method	`killJobs`	Stop and remove all Jobs.
Class Method	`newActor`	Create a new background worker that runs only once after a delay (it may be 0.0s, though), or at a specific time (UTC timestamp).
Class Method	`newWorker`	Create a new background worker that periodically executes the callback.
Class Method	`removeWorkers`	Remove workers from the pool. Before removal they will be stopped first.
Class Method	`runJob`	Run a task as a Thread. Reuse finished threads if possible.
Class Method	`setJobBalance`	Set parameters to balance the number of paused Jobs.
Class Method	`setLogger`	Assign a callback for logging.
Class Method	`stopWorkers`	Stop the worker(s) that match the optional name parameter.
Method	`__new__`	Prevent from instantiation.
Class Variable	`backgroundWorkers`	All background workers.
Class Variable	`queueLock`	Lock for the workerQueue.
Class Variable	`timerLock`	Lock for the workerTimer.
Class Variable	`workerQueue`	Priority queue. Contains tuples (next execution timestamp, worker ID, worker name).
Class Variable	`workerTimer`	A single timer to run the next task in the workerQueue.
Class Method	`_execQueue`	Execute the actual BackgroundWorker's callback in a thread.
Class Method	`_queueWorker`	Queue a `BackgroundWorker` object for execution at the ts timestamp.
Class Method	`_removeBackgroundWorkerFromPool`	Remove a BackgroundWorker object from the internal pool.
Class Method	`_startTimer`	Start the workers queue timer.
Class Method	`_stopTimer`	Cancel/interrupt the workers queue timer.
Class Method	`_unqueueWorker`	Remove the Backgroundworker for `id` from the queue.

@classmethod

def countJobs(cls) -> tuple[int, int]: ¶

Return the number of running and paused Jobs.

Returns
`tuple[int, int]`	Tuple of the integer numbers (count of running and paused `Job` instances).

@classmethod

def findWorkers(cls, name: str | None = None, running: bool | None = None) -> list[BackgroundWorker]: ¶

Find and return a list of worker(s) that match the search criteria.

Parameters
name:`str \| None`	Name of the worker. It may contain simple wildcards (* and ?). If name is None then stop all workers.
running:`bool \| None`	The running status of the worker to match

Returns
`list[BackgroundWorker]`	A list of `BackgroundWorker` objects, or an empty list.

@classmethod

def killJobs(cls): ¶

Stop and remove all Jobs.

@classmethod

Create a new background worker that runs only once after a delay (it may be 0.0s, though), or at a specific time (UTC timestamp).

Parameters
workerCallback:`Callable`	Callback that is executed to perform the action for the actor. It will receive the data in its _data, and the worker itself in the _worker arguments (if available as arguments).
delay:`float \| None`	Delay in seconds after which the actor callback is executed. This is an alternative to at. Only one of at or delay must be specified.
at:`float \| None`	Run the actor at a specific time (timestamp). This is an alternative to delay. Only one of at or delay must be specified.
name:`str \| None`	Name of the actor.
dispose:`bool \| None`	If True then dispose the actor after finish.
finished:`Callable \| None`	Callable that is executed after the worker finished. It will receive the same arguments as the workerCallback callback.
ignoreException:`bool \| None`	Restart the actor in case an exception is encountered.
data:`Any \| None`	Any data structure that is stored in the worker and accessible by the data attribute, and which is passed in the _data argument of the workerCallback if not None.

Returns
`BackgroundWorker`	`BackgroundWorker` object. It is only an initialized object and needs to be started manually with its `start()` method.

@classmethod

Create a new background worker that periodically executes the callback.

Parameters
interval:`float`	Interval in seconds to run the worker callback
workerCallback:`Callable`	Callback to run as a worker
name:`str \| None`	Name of the worker
startWithDelay:`bool \| None`	If True then start the worker after a `interval` delay
maxCount:`int \| None`	Maximum number runs
dispose:`bool \| None`	If True then dispose the worker after finish.
runOnTime:`bool \| None`	If True then the worker is always run at the interval, otherwise the interval starts after the worker execution.
runPastEvents:`bool \| None`	If True then runs in the past are executed, otherwise they are dismissed.
finished:`Callable \| None`	Callable that is executed after the worker finished.
ignoreException:`bool \| None`	Restart the actor in case an exception is encountered.
data:`Any \| None`	Any data structure that is stored in the worker and accessible by the data attribute, and which is passed as the first argument in the _data argument of the workerCallback if not None.

Returns
`BackgroundWorker`	BackgroundWorker

@classmethod

def removeWorkers(cls, name: str) -> list[BackgroundWorker]: ¶

Remove workers from the pool. Before removal they will be stopped first.

Only workers that match the name are removed.

Parameters
name:`str`	Name of the worker(s) to remove. It may contain simple wildcards (* and ?).

Returns
`list[BackgroundWorker]`	The list of removed `BackgroundWorker` objects.

@classmethod

def runJob(cls, task: Callable, name: str | None = None) -> Job: ¶

Run a task as a Thread. Reuse finished threads if possible.

Parameters
task:`Callable`	A Callable that is run as a job. This must include arguments, so a lambda can be used here.
name:`str \| None`	Optional name of the job.

Returns
`Job`	`Job` instance.

@classmethod

def setJobBalance(cls, balanceTarget: float | None = 3.0, balanceLatency: int | None = 1000, balanceReduceFactor: float | None = 2.0): ¶

Set parameters to balance the number of paused Jobs.

Parameters
balanceTarget:`float \| None`	Target balance between paused and running jobs (n paused for 1 running).
balanceLatency:`int \| None`	Number of requests for getting a new Job before a balance check.
balanceReduceFactor:`float \| None`	Factor to reduce the paused jobs (number of paused / balanceReduceFactor).

@classmethod

def setLogger(cls, logger: Callable): ¶

Assign a callback for logging.

Parameters
logger:`Callable`	Logging callback.

@classmethod

def stopWorkers(cls, name: str | None = None) -> list[BackgroundWorker]: ¶

Stop the worker(s) that match the optional name parameter.

Parameters
name:`str \| None`	Name of the worker(s) to remove. It may contain simple wildcards (* and ?). If name is None then stop all workers.

Returns
`list[BackgroundWorker]`	The list of stopped `BackgroundWorker` objects.

def __new__(cls, *args: str, **kwargs: str) -> BackgroundWorkerPool: ¶

Prevent from instantiation.

This class has static functions only.

backgroundWorkers: dict[int, BackgroundWorker] = ¶

All background workers.

queueLock: Lock = ¶

Lock for the workerQueue.

timerLock: Lock = ¶

Lock for the workerTimer.

workerQueue: list[WorkerEntry] = ¶

Priority queue. Contains tuples (next execution timestamp, worker ID, worker name).

workerTimer: Timer = ¶

A single timer to run the next task in the workerQueue.

@classmethod

def _execQueue(cls): ¶

Execute the actual BackgroundWorker's callback in a thread.

@classmethod

def _queueWorker(cls, ts: float, worker: BackgroundWorker): ¶

Queue a BackgroundWorker object for execution at the ts timestamp.

Parameters
ts:`float`	Timestamp at which the worker shall be executed.
worker:`BackgroundWorker`	Backgroundworker object to queue.

@classmethod

def _removeBackgroundWorkerFromPool(cls, worker: BackgroundWorker): ¶

Remove a BackgroundWorker object from the internal pool.

Parameters
worker:`BackgroundWorker`	Backgroundworker objects to remove.

@classmethod

def _startTimer(cls): ¶

Start the workers queue timer.

@classmethod

def _stopTimer(cls): ¶

Cancel/interrupt the workers queue timer.

@classmethod

def _unqueueWorker(cls, worker: BackgroundWorker): ¶

Remove the Backgroundworker for id from the queue.

Parameters
worker:`BackgroundWorker`	Backgroundworker to unqueue