bibliopixel.util.threads.runnable module

class bibliopixel.util.threads.runnable.LoopThread(daemon=True, **kwds)

Bases: bibliopixel.util.threads.runnable.Runnable

is_alive()

Is this Runnable still executing code?

In some cases, such as threads, self.is_alive() might be true for some time after self.running has turned False.

run()

start()

class bibliopixel.util.threads.runnable.QueueHandler(timeout=0.1, send=None, **kwds)

Bases: bibliopixel.util.threads.runnable.LoopThread

run_once()

The target code that is repeatedly executed in the run method

send(msg)

class bibliopixel.util.threads.runnable.Runnable

Bases: object

Base class for all objects that contain threads - including threads created and started by bp code, and threads started by external libraries.

There are three possible thread categories for a Runnable:

1. Runs on the master thread - M
2. A new thread created by us - N
3. A new external thread created by some third-party code - X

Case X is tricky because we would like our code to be called at the start of the new thread, and again at the end of that thread, but we can’t.

Lifecycle - what a Runnable does, and what threads it could be called on

• construction: M
• start: M
• on_start: M * called on the master thread after any new thread has started up
• run: MN
• callbacks: MNX
• join: M
• cleanup: M(N?)

TODO: right now we run all our cleanups on the new thread, if there is a new thread, otherwise on the master thread. Should we move to doing all the cleanups on the master thread?

The way to use a Runnable is like a context manager:

with some_runnable() as runnable:

add_some_callbacks(runnable) more_stuff_that_runs_on_start()

# Depending on the thread category, the Runnable isn’t guaranteed to # actually “go off” until the end of this block.

We’re going to call the code inside the context manager on_start

EXTERNAL = 'X'

MASTER = 'M'

NEW = 'N'

category = 'N'

cleanup()

Cleans up resources after the Runnable.

self.cleanup() may not throw an exception.

is_alive()

Is this Runnable still executing code?

In some cases, such as threads, self.is_alive() might be true for some time after self.running has turned False.

run()

run_once()

The target code that is repeatedly executed in the run method

run_until_stop()

A context manager that starts this Runnable, yields, and then waits for it to finish.

running

Is this Runnable expected to make any progress from here?

The Runnable might still execute a little code after it has stopped running.

start()

stop()

timeout = 0.1

wait()