traits_futures.base_future module

Base class providing common pieces of the Future machinery.

traits_futures.base_future.ABANDONED = 'abandoned'

Control message sent when the callable is abandoned before execution.

class traits_futures.base_future.BaseFuture

Bases: traits.has_traits.HasStrictTraits

Convenience base class for the various flavours of Future.

cancel()

Request cancellation of the background task.

A task in WAITING or EXECUTING state will immediately be moved to CANCELLING state. If the task is not in WAITING or EXECUTING state, this function does nothing.

Changed in version 0.3.0: This method no longer raises for a task that isn’t cancellable. In previous versions, RuntimeError was raised.

Returns

cancelled – True if the task was cancelled, False if the task was not cancellable.

Return type

bool

cancellable = Property(Bool())

True if cancellation of the background task can be requested, else False. Cancellation of the background task can be requested only if the future’s state is either WAITING or EXECUTING.

dispatch(message)

Dispatch a message arriving from the associated BaseTask.

This is a convenience function, and may be safely overridden by subclasses that want to use a different dispatch mechanism. For a message type msgtype, it looks for a method called _process_<msgtype> and dispatches the message arguments to that method. Subclasses then only need to provide the appropriate _process_<msgtype> methods.

Parameters

message (object) – Message sent by the background task. The default implementation of this method expects the message to be in the form (message_type, message_args) with message_type a string.

done = Property(Bool())

True when communications from the background task are complete. At that point, no further state changes can occur for this future. This trait has value True if the state is one of COMPLETED, FAILED, or CANCELLED. It’s safe to listen to this trait for changes: it will always fire exactly once, and when it fires its value will be consistent with that of the state trait.

property exception

Information about any exception raised by the background task.

This attribute is only available if the state of this future is FAILED. If the future has not reached the FAILED state, any attempt to access this attribute will raise an AttributeError.

Returns

exc_info – Tuple containing exception information in string form: (exception type, exception value, formatted traceback).

Return type

tuple

Raises

AttributeError – If the task is still executing, or was cancelled, or completed without raising an exception.

receive(message)

Receive and process a message from the task associated to this future.

This method is primarily for use by the executors, but may also be of use in testing.

Parameters

message (object) – The message received from the associated task.

Returns

final – True if the received message should be the last one ever received from the paired task.

Return type

bool

property result

Result of the background task.

This attribute is only available if the state of the future is COMPLETED. If the future has not reached the COMPLETED state, any attempt to access this attribute will raise an AttributeError.

Returns

result – The result obtained from the background task.

Return type

object

Raises

AttributeError – If the task is still executing, or was cancelled, or raised an exception instead of returning a result.

state = message

The state of the background task, to the best of the knowledge of this future. One of the six constants WAITING, EXECUTING, COMPLETED, FAILED, CANCELLING or CANCELLED.

class traits_futures.base_future.BaseTask

Bases: abc.ABC

Mixin for background task classes, making those classes callable.

This class provides a callable wrapper allowing subclasses to easily provide a background callable task.

Subclasses should override the run method to customize what should happen when the task runs. This class’s __call__ implementation will take care of sending standard control messages telling the future that the task has started, completed, or raised, and delegate to the run method for execution of the background task and sending of any custom messages.

cancelled()

Determine whether the user has requested cancellation.

Returns True if the user has requested cancellation via the associated future’s cancel method, and False otherwise.

Returns

Return type

bool

abstract run()

Run the body of the background task.

Returns

any – May return any object. That object will be delivered to the future’s result attribute.

Return type

object

send(message_type, message_arg=None)

Send a message to the associated future.

Parameters

• message_type (str) – The type of the message. This is used by BaseFuture when dispatching messages to appropriate handlers.

• message_arg (object, optional) – Message argument, if any. If not given, None is used.

traits_futures.base_future.FINAL_MESSAGES = {'abandoned', 'raised', 'returned'}

Message types that indicate a “final” message. After a message of this type is received, no more messages will be received.

traits_futures.base_future.RAISED = 'raised'

Control message sent when an exception was raised by the background callable. The argument is a tuple containing exception information.

traits_futures.base_future.RETURNED = 'returned'

Control message sent to indicate that the background callable succeeded and returned a result. The argument is that result.

traits_futures.base_future.SENT = 'sent'

Custom message from the future. The argument is a pair (message_type, message_args); the message type and message args are interpreted by the future.

traits_futures.base_future.STARTED = 'started'

Control message sent before we start to process the target callable. The argument is always None.

exception traits_futures.base_future.TaskCancelled

Bases: Exception

Exception raised within the background task on cancellation.