traits_futures.api module

Core API for the traits_futures package.

class traits_futures.api.CallFuture

Bases: traits.has_traits.HasStrictTraits

Object representing the front-end handle to a background call.

cancel()

Method that can be called from the main thread to indicate that the task should be cancelled (provided it hasn’t already started running).

cancellable = Property(Bool())

True if this task can be cancelled, else False.

done = Property(Bool())

True if we’ve received the final message from the background task, else False. True indicates either that the background task succeeded, or that it raised, or that it was cancelled.

exception = CANCELLING

result = CANCELLING

state = FutureState

The state of the background call, to the best of the knowledge of this future.

class traits_futures.api.IterationFuture

Bases: traits.has_traits.HasStrictTraits

Foreground representation of an iteration executing in the background.

cancel()

Method called from the main thread to request cancellation of the background job.

cancellable = Property(Bool())

True if this task can be cancelled, else False.

done = Property(Bool())

True if we’ve received the final message from the background iteration, else False. True indicates either that the background iteration succeeded, or that it raised, or that it was cancelled.

exception = CANCELLING

result_event = Event(Any())

Event fired whenever a result arrives from the background iteration.

state = FutureState

The state of the background iteration, to the best of the knowledge of this future.

class traits_futures.api.ProgressFuture

Bases: traits.has_traits.HasStrictTraits

Object representing the front-end handle to a ProgressBackgroundTask.

cancel()

Method that can be called from the main thread to indicate that the task should be cancelled (provided it hasn’t already started running).

cancellable = Property(Bool())

True if this task can be cancelled, else False.

done = Property(Bool())

True if we’ve received the final message from the background task, else False. True indicates either that the background task succeeded, or that it raised, or that it was cancelled.

exception = CANCELLING

progress = Event(Any())

Event fired whenever a progress message arrives from the background.

result = CANCELLING

state = FutureState

The state of the background task, to the best of the knowledge of this future.

class traits_futures.api.TraitsExecutor(thread_pool=None, **traits)

Bases: traits.has_traits.HasStrictTraits

Executor to initiate and manage background tasks.

running = Property(Bool())

Derived state: true if this executor is running; False if it’s stopped or stopping.

state = ExecutorState

Current state of this executor.

stop()

Initiate stop: cancel existing jobs and prevent new ones.

stopped = Property(Bool())

Derived state: true if this executor is stopped and it’s safe to dispose of related resources (like the thread pool).

submit(task)

Submit a task to the executor, and return the corresponding future.

Parameters:task (BackgroundCall, BackgroundIteration or BackgroundProgress) – The task to be executed. Returns:future – Future for this task. Return type:CallFuture, IterationFuture or ProgressFuture

submit_call(callable, *args, **kwargs)

Convenience function to submit a background call.

Parameters:

• callable (an arbitrary callable) – Function to execute in the background.
• *args – Positional arguments to pass to that function.
• **kwargs – Named arguments to pass to that function.

Returns:

future – Object representing the state of the background call.

Return type:

CallFuture

submit_iteration(callable, *args, **kwargs)

Convenience function to submit a background iteration.

Parameters:

• callable (an arbitrary callable) – Function executed in the background to provide the iterable.
• *args – Positional arguments to pass to that function.
• **kwargs – Named arguments to pass to that function.

Returns:

future – Object representing the state of the background iteration.

Return type:

IterationFuture

submit_progress(callable, *args, **kwargs)

Convenience function to submit a background progress call.

Parameters:

• callable (callable accepting a "progress" named argument) – Function executed in the background to provide the iterable. This should accept a “progress” named argument. The callable can then call the “progress” object to report progress.
• *args – Positional arguments to pass to that function.
• **kwargs – Named arguments to pass to that function. These should not include “progress”.

Returns:

future – Object representing the state of the background task.

Return type:

ProgressFuture