satella.coding.concurrent.futures package¶
Submodules¶
satella.coding.concurrent.futures.call_in_future module¶
- satella.coding.concurrent.futures.call_in_future.call_in_future(executor, function, *args, **kwargs)¶
Return a callable, whose calling will schedule function to be executed on a target Executor.
The returned function will accept any number of arguments and keyword arguments, but will simply ignore them.
- Parameters:
executor (Executor) – executor to run at
function (Callable) – callable to schedule
args – arguments to provide to the callable
kwargs – keyword arguments to provide to the callable
- Returns:
a callable, calling which will schedule function to run at executor. Calling this callable will return the Future for that function
- Return type:
Callable[[], Future]
satella.coding.concurrent.futures.collection module¶
- class satella.coding.concurrent.futures.collection.FutureCollection(futures=())¶
Bases:
object
A set of futures sharing a common result, or a common exception.
This overloads the operator + for making an union of futures. It can be used with either instances of
FutureCollection
or normal futures.Also supports the indexing operator to get n-th future.
- Parameters:
futures (Sequence[Future]) –
- add(future)¶
Add a future
- Parameters:
future (Future) – a Future to add
- Returns:
self
- Return type:
- add_done_callback(callback, only_one=False)¶
Add a callback to a Future to be called on it’s completion.
By default, this will add the callback to all futures.
- Parameters:
callback – callback that takes the completed Future as argument
only_one (bool) – callback will be added only to a single Future. False by default
- Raises:
IndexError – only_one was given and no Futures in collection!
- Return type:
None
- cancel()¶
Cancel all futures
- Returns:
True if all sections were cancelled
- Return type:
bool
- exception(timeout=None)¶
Return first exception raised by any of the futures
This will block until the results are available. This call proceeding does not mean that results for all are available, since this will return the first exception encountered!
- Parameters:
timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary
- Returns:
the first exception, or None if there were no exceptions
- Raises:
WouldWaitMore – timeout while waiting for result
- Return type:
Optional[Exception]
- futures¶
- result(timeout=None)¶
Return the result of all futures, as a list.
This will block until the results are available.
- Parameters:
timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary
- Returns:
list containing results of all futures
- Raises:
WouldWaitMore – timeout while waiting for result
- Return type:
list
- set_exception(exc)¶
Set an exception for all futures
- Parameters:
exc – exception instance to set
- Return type:
None
- set_result(result)¶
Set a result for all futures
- Parameters:
result – result to set
- Return type:
None
- set_running_or_notify_cancel()¶
Call
set_running_or_notify_cancel
on the futuresThis will return True if at least one future was not cancelled
- Return type:
bool
satella.coding.concurrent.futures.futures module¶
- class satella.coding.concurrent.futures.futures.Future¶
Bases:
Future
,Generic
[T
]A future that allows it’s callback handlers to change it’s result before presenting it to the user.
Use like this:
>>> fut = Future() >>> fut.set_running_or_notify_cancel() >>> def transform_future(future): >>> future.set_result(future.result() + 2) >>> fut.add_pre_done_callback(transform_future) >>> fut.set_result(2) >>> assert fut.result() == 4
Initializes the future. Should not be called by clients.
- add_pre_done_callback(fn)¶
Attaches a callable that will be called just before the future finishes and can change the future’s result (or insert an Exception).
- Args:
- fn: A callable that will be called with this future as its only
argument just before the future completes or is cancelled.
- chain(fun)¶
Schedule function to be called with the result of this future as it’s argument (or exception value if the future excepted).
- Parameters:
fun – function to call
- Returns:
self
- Return type:
- exception(timeout)¶
Return the exception raised by the call that the future represents.
- Args:
- timeout: The number of seconds to wait for the exception if the
future isn’t done. If None, then there is no limit on the wait time.
- Returns:
The exception raised by the call that the future represents or None if the call completed without raising.
- Raises:
CancelledError: If the future was cancelled. TimeoutError: If the future didn’t finish executing before the given
timeout.
- Parameters:
timeout (None) –
- Return type:
Type[Exception]
- on_failure(fun)¶
Schedule function to be called with the exception value that befall this future
- Parameters:
fun – function to call
- Returns:
self
- on_success(fun)¶
Schedule function to be called with the result of this future as it’s argument only if this future succeeds.
- Parameters:
fun – function to call
- Returns:
self
- Return type:
- result(timeout=None)¶
Return the result of the call that the future represents.
- Args:
- timeout: The number of seconds to wait for the result if the future
isn’t done. If None, then there is no limit on the wait time.
- Returns:
The result of the call that the future represents.
- Raises:
CancelledError: If the future was cancelled. TimeoutError: If the future didn’t finish executing before the given
timeout.
Exception: If the call raised then that exception will be raised.
- Return type:
T
- set_exception(exception)¶
Sets the result of the future as being the given exception.
Should only be used by Executor implementations and unit tests.
- set_result(result)¶
Sets the return value of work associated with the future.
Should only be used by Executor implementations and unit tests.
- Parameters:
result (T) –
- Return type:
None
- class satella.coding.concurrent.futures.futures.WrappingFuture(source_future)¶
Bases:
Future
A Satella future wrapping an existing Python future.
Use like:
>> wrapped = WrappingFuture(existing_python_future)
Initializes the future. Should not be called by clients.
- Parameters:
source_future (Future) –
- cancel()¶
Cancel the future if possible.
Returns True if the future was cancelled, False otherwise. A future cannot be cancelled if it is running or has already completed.
- Return type:
bool
- set_running_or_notify_cancel()¶
Mark the future as running or process any cancel notifications.
Should only be used by Executor implementations and unit tests.
If the future has been cancelled (cancel() was called and returned True) then any threads waiting on the future completing (though calls to as_completed() or wait()) are notified and False is returned.
If the future was not cancelled then it is put in the running state (future calls to running() will return True) and True is returned.
This method should be called by Executor implementations before executing the work associated with this future. If this method returns False then the work should not be executed.
- Returns:
False if the Future was cancelled, True otherwise.
- Raises:
- RuntimeError: if this method was already called or if set_result()
or set_exception() was called.
- Return type:
bool
satella.coding.concurrent.futures.wrapped_executor module¶
- class satella.coding.concurrent.futures.wrapped_executor.ExecutorWrapper(executor)¶
Bases:
Executor
A wrapping for Python executors to return Satella futures instead of standard Python ones.
- Parameters:
executor (Executor) –
- shutdown(wait=True)¶
Clean-up the resources associated with the Executor.
It is safe to call this method several times. Otherwise, no other methods can be called after this one.
- Args:
- wait: If True then shutdown will not return until all running
futures have finished executing and the resources used by the executor have been reclaimed.
Module contents¶
- class satella.coding.concurrent.futures.ExecutorWrapper(executor)¶
Bases:
Executor
A wrapping for Python executors to return Satella futures instead of standard Python ones.
- Parameters:
executor (Executor) –
- shutdown(wait=True)¶
Clean-up the resources associated with the Executor.
It is safe to call this method several times. Otherwise, no other methods can be called after this one.
- Args:
- wait: If True then shutdown will not return until all running
futures have finished executing and the resources used by the executor have been reclaimed.
- class satella.coding.concurrent.futures.Future¶
Bases:
Future
,Generic
[T
]A future that allows it’s callback handlers to change it’s result before presenting it to the user.
Use like this:
>>> fut = Future() >>> fut.set_running_or_notify_cancel() >>> def transform_future(future): >>> future.set_result(future.result() + 2) >>> fut.add_pre_done_callback(transform_future) >>> fut.set_result(2) >>> assert fut.result() == 4
Initializes the future. Should not be called by clients.
- add_pre_done_callback(fn)¶
Attaches a callable that will be called just before the future finishes and can change the future’s result (or insert an Exception).
- Args:
- fn: A callable that will be called with this future as its only
argument just before the future completes or is cancelled.
- chain(fun)¶
Schedule function to be called with the result of this future as it’s argument (or exception value if the future excepted).
- Parameters:
fun – function to call
- Returns:
self
- Return type:
- exception(timeout)¶
Return the exception raised by the call that the future represents.
- Args:
- timeout: The number of seconds to wait for the exception if the
future isn’t done. If None, then there is no limit on the wait time.
- Returns:
The exception raised by the call that the future represents or None if the call completed without raising.
- Raises:
CancelledError: If the future was cancelled. TimeoutError: If the future didn’t finish executing before the given
timeout.
- Parameters:
timeout (None) –
- Return type:
Type[Exception]
- on_failure(fun)¶
Schedule function to be called with the exception value that befall this future
- Parameters:
fun – function to call
- Returns:
self
- on_success(fun)¶
Schedule function to be called with the result of this future as it’s argument only if this future succeeds.
- Parameters:
fun – function to call
- Returns:
self
- Return type:
- result(timeout=None)¶
Return the result of the call that the future represents.
- Args:
- timeout: The number of seconds to wait for the result if the future
isn’t done. If None, then there is no limit on the wait time.
- Returns:
The result of the call that the future represents.
- Raises:
CancelledError: If the future was cancelled. TimeoutError: If the future didn’t finish executing before the given
timeout.
Exception: If the call raised then that exception will be raised.
- Return type:
T
- set_exception(exception)¶
Sets the result of the future as being the given exception.
Should only be used by Executor implementations and unit tests.
- set_result(result)¶
Sets the return value of work associated with the future.
Should only be used by Executor implementations and unit tests.
- Parameters:
result (T) –
- Return type:
None
- class satella.coding.concurrent.futures.FutureCollection(futures=())¶
Bases:
object
A set of futures sharing a common result, or a common exception.
This overloads the operator + for making an union of futures. It can be used with either instances of
FutureCollection
or normal futures.Also supports the indexing operator to get n-th future.
- Parameters:
futures (Sequence[Future]) –
- add(future)¶
Add a future
- Parameters:
future (Future) – a Future to add
- Returns:
self
- Return type:
- add_done_callback(callback, only_one=False)¶
Add a callback to a Future to be called on it’s completion.
By default, this will add the callback to all futures.
- Parameters:
callback – callback that takes the completed Future as argument
only_one (bool) – callback will be added only to a single Future. False by default
- Raises:
IndexError – only_one was given and no Futures in collection!
- Return type:
None
- cancel()¶
Cancel all futures
- Returns:
True if all sections were cancelled
- Return type:
bool
- exception(timeout=None)¶
Return first exception raised by any of the futures
This will block until the results are available. This call proceeding does not mean that results for all are available, since this will return the first exception encountered!
- Parameters:
timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary
- Returns:
the first exception, or None if there were no exceptions
- Raises:
WouldWaitMore – timeout while waiting for result
- Return type:
Optional[Exception]
- futures¶
- result(timeout=None)¶
Return the result of all futures, as a list.
This will block until the results are available.
- Parameters:
timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary
- Returns:
list containing results of all futures
- Raises:
WouldWaitMore – timeout while waiting for result
- Return type:
list
- set_exception(exc)¶
Set an exception for all futures
- Parameters:
exc – exception instance to set
- Return type:
None
- set_result(result)¶
Set a result for all futures
- Parameters:
result – result to set
- Return type:
None
- set_running_or_notify_cancel()¶
Call
set_running_or_notify_cancel
on the futuresThis will return True if at least one future was not cancelled
- Return type:
bool
- exception satella.coding.concurrent.futures.InvalidStateError¶
Bases:
Error
The operation is not allowed in this state.
- class satella.coding.concurrent.futures.WrappingFuture(source_future)¶
Bases:
Future
A Satella future wrapping an existing Python future.
Use like:
>> wrapped = WrappingFuture(existing_python_future)
Initializes the future. Should not be called by clients.
- Parameters:
source_future (Future) –
- cancel()¶
Cancel the future if possible.
Returns True if the future was cancelled, False otherwise. A future cannot be cancelled if it is running or has already completed.
- Return type:
bool
- set_running_or_notify_cancel()¶
Mark the future as running or process any cancel notifications.
Should only be used by Executor implementations and unit tests.
If the future has been cancelled (cancel() was called and returned True) then any threads waiting on the future completing (though calls to as_completed() or wait()) are notified and False is returned.
If the future was not cancelled then it is put in the running state (future calls to running() will return True) and True is returned.
This method should be called by Executor implementations before executing the work associated with this future. If this method returns False then the work should not be executed.
- Returns:
False if the Future was cancelled, True otherwise.
- Raises:
- RuntimeError: if this method was already called or if set_result()
or set_exception() was called.
- Return type:
bool
- satella.coding.concurrent.futures.call_in_future(executor, function, *args, **kwargs)¶
Return a callable, whose calling will schedule function to be executed on a target Executor.
The returned function will accept any number of arguments and keyword arguments, but will simply ignore them.
- Parameters:
executor (Executor) – executor to run at
function (Callable) – callable to schedule
args – arguments to provide to the callable
kwargs – keyword arguments to provide to the callable
- Returns:
a callable, calling which will schedule function to run at executor. Calling this callable will return the Future for that function
- Return type:
Callable[[], Future]