Executor

Executor is an abstract class that provides methods to execute callsasynchronously.

submit(fn,*args,**kwargs)

Schedules the callable to be executed asfn(*args,**kwargs)and returns aFuture instance representing the execution of thecallable.

This is an abstract method and must be implemented by Executorsubclasses.

map(func,*iterables,timeout=None)

Equivalent tomap(func,*iterables) but func is executedasynchronously and several calls to func may be made concurrently.The returned iterator raises aTimeoutError if__next__() iscalled and the result isn’t available aftertimeout seconds fromthe original call tomap(). Iftimeout is not specified orNone then there is no limit to the wait time. If a call raisesan exception then that exception will be raised when its value isretrieved from the iterator.

shutdown(wait=True)

Signal the executor that it should free any resources that it isusing when the currently pending futures are done executing.Calls toExecutor.submit andExecutor.map and made aftershutdown will raiseRuntimeError.

If wait isTrue then this method will not return until all thepending futures are done executing and the resources associatedwith the executor have been freed. If wait isFalse then thismethod will return immediately and the resources associated withthe executor will be freed when all pending futures are doneexecuting. Regardless of the value of wait, the entire Pythonprogram will not exit until all pending futures are doneexecuting.

When using an executor as a context manager,__exit__ will callExecutor.shutdown(wait=True).

ProcessPoolExecutor

TheProcessPoolExecutor class is anExecutor subclass that uses apool of processes to execute calls asynchronously. The callableobjects and arguments passed toProcessPoolExecutor.submit must bepickleable according to the same limitations as the multiprocessingmodule.

CallingExecutor orFuture methods from within a callablesubmitted to aProcessPoolExecutor will result in deadlock.

__init__(max_workers)

Executes calls asynchronously using a pool of a mostmax_workersprocesses. Ifmax_workers isNone or not given then as manyworker processes will be created as the machine has processors.

ThreadPoolExecutor

TheThreadPoolExecutor class is anExecutor subclass that uses apool of threads to execute calls asynchronously.

Deadlock can occur when the callable associated with aFuture waitson the results of anotherFuture. For example:

importtimedefwait_on_b():time.sleep(5)print(b.result())# b will never complete because it is waiting on a.return5defwait_on_a():time.sleep(5)print(a.result())# a will never complete because it is waiting on b.return6executor=ThreadPoolExecutor(max_workers=2)a=executor.submit(wait_on_b)b=executor.submit(wait_on_a)

And:

defwait_on_future():f=executor.submit(pow,5,2)# This will never complete because there is only one worker thread and# it is executing this function.print(f.result())executor=ThreadPoolExecutor(max_workers=1)executor.submit(wait_on_future)

__init__(max_workers)

Executes calls asynchronously using a pool of at mostmax_workers threads.

Future Objects

TheFuture class encapsulates the asynchronous execution of acallable.Future instances are returned byExecutor.submit.

cancel()

Attempt to cancel the call. If the call is currently beingexecuted then it cannot be cancelled and the method will returnFalse, otherwise the call will be cancelled and the method willreturnTrue.

cancelled()

ReturnTrue if the call was successfully cancelled.

running()

ReturnTrue if the call is currently being executed and cannotbe cancelled.

done()

ReturnTrue if the call was successfully cancelled or finishedrunning.

result(timeout=None)

Return the value returned by the call. If the call hasn’t yetcompleted then this method will wait up totimeout seconds. Ifthe call hasn’t completed intimeout seconds then aTimeoutError will be raised. Iftimeout is not specified orNone then there is no limit to the wait time.

If the future is cancelled before completing thenCancelledErrorwill be raised.

If the call raised then this method will raise the same exception.

exception(timeout=None)

Return the exception raised by the call. If the call hasn’t yetcompleted then this method will wait up totimeout seconds. Ifthe call hasn’t completed intimeout seconds then aTimeoutError will be raised. Iftimeout is not specified orNone then there is no limit to the wait time.

If the future is cancelled before completing thenCancelledErrorwill be raised.

If the call completed without raising thenNone is returned.

add_done_callback(fn)

Attaches a callablefn to the future that will be called whenthe future is cancelled or finishes running.fn will be calledwith the future as its only argument.

Added callables are called in the order that they were added andare always called in a thread belonging to the process that addedthem. If the callable raises anException then it will belogged and ignored. If the callable raises anotherBaseException then behavior is not defined.

If the future has already completed or been cancelled thenfnwill be called immediately.

Module Functions

wait(fs,timeout=None,return_when=ALL_COMPLETED)

Wait for theFuture instances (possibly created by differentExecutor instances) given byfs to complete. Returns a named2-tuple of sets. The first set, named “done”, contains thefutures that completed (finished or were cancelled) before thewait completed. The second set, named “not_done”, containsuncompleted futures.

timeout can be used to control the maximum number of seconds towait before returning. If timeout is not specified or None thenthere is no limit to the wait time.

return_when indicates when the method should return. It must beone of the following constants:

Constant	Description
FIRST_COMPLETED	The method will return when any future finishes oris cancelled.
FIRST_EXCEPTION	The method will return when any future finishes byraising an exception. If not future raises anexception then it is equivalent to ALL_COMPLETED.
ALL_COMPLETED	The method will return when all calls finish.

as_completed(fs,timeout=None)

Returns an iterator over theFuture instances given byfs thatyields futures as they complete (finished or were cancelled). Anyfutures that completed beforeas_completed() was called will beyielded first. The returned iterator raises aTimeoutError if__next__() is called and the result isn’t available aftertimeout seconds from the original call toas_completed(). Iftimeout is not specified orNone then there is no limit to thewait time.

TheFuture instances can have been created by differentExecutor instances.