threadgroup¶

class oslo_service.threadgroup.Thread(thread, group, link=True)¶

Bases: object

Wrapper around a greenthread.

Holds a reference to the ThreadGroup. The Thread will notify the ThreadGroup when it has done so it can be removed from the threads list.

cancel(*throw_args)¶

Prevent the thread from starting if it has not already done so.

Parameters

throw_args – the exc_info data to raise from wait().

property ident¶

link(func, *args, **kwargs)¶

Schedule a function to be run upon completion of the thread.

stop()¶

Kill the thread by raising GreenletExit within it.

wait()¶

Block until the thread completes and return the result.

class oslo_service.threadgroup.ThreadGroup(thread_pool_size=10)¶

Bases: object

A group of greenthreads and timers.

The point of the ThreadGroup class is to:

• keep track of timers and greenthreads (making it easier to stop them when need be).

• provide an easy API to add timers.

Note

The API is inconsistent, confusing, and not orthogonal. The same verbs often mean different things when applied to timers and threads, respectively. Read the documentation carefully.

add_dynamic_timer(callback, initial_delay=None, periodic_interval_max=None, *args, **kwargs)¶

Add a timer that controls its own period dynamically.

The period of each iteration of the timer is controlled by the return value of the callback function on the previous iteration.

Warning

Passing arguments to the callback function is deprecated. Use the add_dynamic_timer_args() method to pass arguments for the callback function.

Parameters

• callback – The callback function to run when the timer is triggered.

• initial_delay – The delay in seconds before first triggering the timer. If not set, the timer is liable to be scheduled immediately.

• periodic_interval_max – The maximum interval in seconds to allow the callback function to request. If provided, this is also used as the default delay if None is returned by the callback function.

Returns

an oslo_service.loopingcall.DynamicLoopingCall instance

add_dynamic_timer_args(callback, args=None, kwargs=None, initial_delay=None, periodic_interval_max=None, stop_on_exception=True)¶

Add a timer that controls its own period dynamically.

The period of each iteration of the timer is controlled by the return value of the callback function on the previous iteration.

Parameters

• callback – The callback function to run when the timer is triggered.

• args – A list of positional args to the callback function.

• kwargs – A dict of keyword args to the callback function.

• initial_delay – The delay in seconds before first triggering the timer. If not set, the timer is liable to be scheduled immediately.

• periodic_interval_max – The maximum interval in seconds to allow the callback function to request. If provided, this is also used as the default delay if None is returned by the callback function.

• stop_on_exception – Pass False to have the timer continue running even if the callback function raises an exception.

Returns

an oslo_service.loopingcall.DynamicLoopingCall instance

add_thread(callback, *args, **kwargs)¶

Spawn a new thread.

This call will block until capacity is available in the thread pool. After that, it returns immediately (i.e. before the new thread is scheduled).

Parameters

• callback – the function to run in the new thread.

• args – positional arguments to the callback function.

• kwargs – keyword arguments to the callback function.

Returns

a Thread object

add_timer(interval, callback, initial_delay=None, *args, **kwargs)¶

Add a timer with a fixed period.

Warning

Passing arguments to the callback function is deprecated. Use the add_timer_args() method to pass arguments for the callback function.

Parameters

• interval – The minimum period in seconds between calls to the callback function.

• callback – The callback function to run when the timer is triggered.

• initial_delay – The delay in seconds before first triggering the timer. If not set, the timer is liable to be scheduled immediately.

Returns

an oslo_service.loopingcall.FixedIntervalLoopingCall instance

add_timer_args(interval, callback, args=None, kwargs=None, initial_delay=None, stop_on_exception=True)¶

Add a timer with a fixed period.

Parameters

• interval – The minimum period in seconds between calls to the callback function.

• callback – The callback function to run when the timer is triggered.

• args – A list of positional args to the callback function.

• kwargs – A dict of keyword args to the callback function.

• initial_delay – The delay in seconds before first triggering the timer. If not set, the timer is liable to be scheduled immediately.

• stop_on_exception – Pass False to have the timer continue running even if the callback function raises an exception.

Returns

an oslo_service.loopingcall.FixedIntervalLoopingCall instance

cancel(*throw_args, **kwargs)¶

Cancel unstarted threads in the group, and optionally stop the rest.

Warning

This method is deprecated and should not be used. It will be removed in a future release.

If called without the timeout argument, this does not stop any running threads, but prevents any threads in the group that have not yet started from running, then returns immediately. Timers are not affected.

If the ‘timeout’ argument is supplied, then it serves as a grace period to allow running threads to finish. After the timeout, any threads in the group that are still running will be killed by raising GreenletExit in them, and all timers will be stopped (so that they are not retriggered - timer calls that are in progress will not be interrupted). This method will not block until all threads have actually exited, nor that all in-progress timer calls have completed. To guarantee that all threads have exited, call wait(). If all threads complete before the timeout expires, timers will be left running; there is no way to then stop those timers, so for consistent behaviour :func`stop_timers` should be called before calling this method.

Parameters

• throw_args – the exc_info data to raise from Thread.wait() for any of the unstarted threads. (Though note that ThreadGroup.wait() suppresses exceptions.)

• timeout – time to wait for running threads to complete before calling stop(). If not supplied, threads that are already running continue to completion.

• wait_time – length of time in seconds to sleep between checks of whether any threads are still alive. (Default 1s.)

stop(graceful=False)¶

Stop all timers and threads in the group.

No new invocations of timers will be triggered after they are stopped, but calls that are in progress will not be interrupted.

If graceful is false, kill all threads immediately by raising GreenletExit. Note that in this case, this method will not block until all threads and running timer callbacks have actually exited. To guarantee that all threads have exited, call wait().

If graceful is true, do not kill threads. Block until all threads and running timer callbacks have completed. This is equivalent to calling stop_timers() with wait=True followed by wait().

Parameters

graceful – If true, block until all timers have stopped and all threads completed; never kill threads. Otherwise, kill threads immediately and return immediately even if there are timer callbacks still running.

stop_timers(wait=False)¶

Stop all timers in the group and remove them from the group.

No new invocations of timers will be triggered after they are stopped, but calls that are in progress will not be interrupted.

To wait for in-progress calls to complete, pass wait=True - calling wait() will not have the desired effect as the timers will have already been removed from the group.

Parameters

wait – If true, block until all timers have been stopped before returning.

thread_done(thread)¶

Remove a completed thread from the group.

This method is automatically called on completion of a thread in the group, and should not be called explicitly.

timer_done(timer)¶

Remove a timer from the group.

Parameters

timer – The timer object returned from add_timer() or its analogues.

wait()¶

Block until all timers and threads in the group are complete.

Note

Before calling this method, any timers should be stopped first by calling stop_timers(), stop(), or cancel() with a timeout argument. Otherwise this will block forever.

Note

Calling stop_timers() removes the timers from the group, so a subsequent call to this method will not wait for any in-progress timer calls to complete.

Any exceptions raised by the threads will be logged but suppressed.

Note

This call guarantees only that the threads themselves have completed, not that any cleanup functions added via Thread.link() have completed.