traits_futures.multithreading_router module

Implementations of the IMessageSender, IMessageReceiver and IMessageRouter interfaces for tasks executed on a background thread.

class traits_futures.multithreading_router.MultithreadingReceiver

Bases: traits.has_traits.HasStrictTraits

Implementation of the IMessageReceiver interface for the case where the sender will be in a background thread.

connection_id = Int()

Connection id, matching that of the paired sender.

message = Event(Any())

Event fired when a message is received from the paired sender.

class traits_futures.multithreading_router.MultithreadingRouter(**traits)

Bases: traits.has_traits.HasRequiredTraits

Implementation of the IMessageRouter interface for the case where the sender will be in a background thread.

Parameters

event_loop (IEventLoop) – The event loop used to trigger message dispatch.

close_pipe(receiver)

Close the receiver end of a pipe produced by pipe.

Removes the receiver from the routing table, so that no new messages can reach that receiver.

Not thread safe. Must always be called in the main thread.

Parameters

receiver (MultithreadingReceiver) – Receiver half of the pair returned by the pipe method.

Raises

RuntimeError – If the router is not currently running.

event_loop = Instance(IEventLoop, required=True)

The event loop used to trigger message dispatch.

pipe()

Create a (sender, receiver) pair for sending and receiving messages.

The sender will be passed to the background task and used to send messages, while the receiver remains in the foreground.

Not thread safe. Must always be called in the main thread.

Returns

• sender (MultithreadingSender) – Object to be passed to the background task.

• receiver (MultithreadingReceiver) – Object kept in the foreground, which reacts to messages.

Raises

RuntimeError – If the router is not currently running.

route_until(condition, timeout=None)

Manually drive the router until a given condition occurs, or timeout.

This is primarily used as part of a clean shutdown.

Note: this has the side-effect of moving the router from “event loop” mode to “manual” mode. This mode switch is permanent, in the sense that after this point, the router will no longer respond to pings: any messages will need to be processed through this function.

Parameters

• condition – Zero-argument callable returning a boolean. When this condition becomes true, this method will stop routing messages. If the condition is already true on entry, no messages will be routed.

• timeout (float, optional) – Maximum number of seconds to route messages for.

Raises

RuntimeError – If the condition did not become true before timeout.

start()

Start routing messages.

This method must be called before any call to pipe or close_pipe can be made.

Not thread-safe. Must always be called in the main thread.

Raises

RuntimeError – If the router has already been started.

stop()

Stop routing messages.

This method should be called in the main thread after all pipes are finished with. Calls to pipe or close_pipe are not permitted after this method has been called.

Logs a warning if there are unclosed pipes.

Not thread safe. Must always be called in the main thread.

Raises

RuntimeError – If the router is not running.

class traits_futures.multithreading_router.MultithreadingSender(connection_id, pingee, message_queue)

Bases: object

Object allowing the worker to send messages.

This class will be instantiated in the main thread, and the instance passed to the worker thread to allow the worker to communicate back to the main thread.

Parameters

• connection_id (int) – Id of the matching receiver; used for message routing.

• pingee (IPingee) – Recipient for pings, used to notify the event loop that there’s a message pending.

• message_queue (queue.Queue) – Thread-safe queue for passing messages to the foreground.

send(message)

Send a message to the router.

Not thread-safe. The ‘start’, ‘send’ and ‘stop’ methods should all be called from the same thread.

Parameters

message (object) – Typically this will be immutable, small, and pickleable.

Raises

RuntimeError – If the sender has not been started, or has already been stopped.

start()

Do any setup necessary to prepare for sending messages.

This method must be called before any messages can be sent using the send method.

Not thread-safe. The ‘start’, ‘send’ and ‘stop’ methods should all be called from the same thread.

Raises

RuntimeError – If the sender has previously been started.

stop()

Do any teardown.

After this method has been called, no more messages can be sent.

Not thread-safe. The ‘start’, ‘send’ and ‘stop’ methods should all be called from the same thread.

Raises

RuntimeError – If the sender has not been started, or has already been stopped.