traits_futures.traits_executor module

Executor to submit background tasks.

class traits_futures.traits_executor.TraitsExecutor(thread_pool=None, *, worker_pool=None, max_workers=None, context=None, event_loop=None, **traits)

Bases: traits.has_traits.HasStrictTraits

Executor to initiate and manage background tasks.

Parameters

• thread_pool (concurrent.futures.Executor, optional) –

  Deprecated alias for worker_pool.

  Deprecated since version 0.2: Use worker_pool instead.

• worker_pool (concurrent.futures.Executor, optional) – If supplied, provides the underlying worker pool executor to use. In this case, the creator of the TraitsExecutor is responsible for shutting down the worker pool once it’s no longer needed. If not supplied, a new private worker pool will be created, and this object’s stop method will shut down that worker pool.

• max_workers (int or None, optional) – Maximum number of workers for the private worker pool. This parameter is mutually exclusive with worker_pool. The default is None, which delegates the choice of number of workers to Python’s concurrent.futures module.

• context (IParallelContext, optional) – Parallelism context, providing appropriate concurrent primitives and worker pools for a given choice of parallelism (for example multithreading or multiprocessing). If not given, assumes multithreading. Note that if both context and worker_pool are given, they must be compatible.

• event_loop (IEventLoop, optional) – The event loop to use for message dispatch. If not given, uses an ETSEventLoop instance, which determines the appropriate toolkit based on availability and the value of the ETS_TOOLKIT environment variable.

running = Property(Bool())

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

shutdown(*, timeout=None)

Wait for all tasks to complete and then shut this executor down.

All waiting or executing background tasks that are cancellable will be cancelled, and then this executor will wait for all tasks to complete. If a timeout is given and that timeout is reached before all tasks complete, then RuntimeError will be raised and the executor will remain in STOPPING state. Otherwise, on return from this method the executor will be in STOPPED state

This method may be called at any time. If called on an executor that’s already stopped, this method does nothing.

Parameters

timeout (float, optional) – Maximum time to wait for background tasks to complete, in seconds. If not given, this method will wait indefinitely.

Raises

RuntimeError – If a timeout is given, and the background tasks fail to complete within the given timeout.

state = Property(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 worker pool).

submit(task)

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

This method is not thread-safe. It may only be used from the main thread.

Parameters

task (ITaskSpecification) –

Returns

future – Future for this task.

Return type

IFuture

submit_call(callable, *args, **kwargs)

Convenience function to submit a background call.

Deprecated since version 0.2: Use the submit_call function instead.

Parameters

• 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.

Deprecated since version 0.2: Use the submit_iteration function instead.

Parameters

• 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.

Deprecated since version 0.2: Use the submit_progress function instead.

Parameters

• callable – 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