Binding callables to executors: bind, flat_bind

The bind() method produces a callable which is bound to a specific executor.

This is illustrated by the following example. Consider this code to fetch data from a list of URLs expected to provide JSON, with up to 8 concurrent requests and retries on failure, without using bind():

executor = Executors.thread_pool(max_workers=8). \
    with_map(lambda response: response.json()). \
    with_retry()

futures = [executor.submit(requests.get, url)
            for url in urls]

The following code using bind() is functionally equivalent:

async_get = Executors.thread_pool(max_workers=8). \
    bind(requests.get). \
    with_map(lambda response: response.json()). \
    with_retry()

futures = [async_get(url) for url in urls]

The latter example using bind() is more readable because the order of the calls to set up the pipeline more closely reflects the order in which the pipeline executes at runtime.

In contrast, without using bind(), the first step of the pipeline - requests.get() - appears at the end of the code, which is harder to follow.

flat_bind() is also provided for use with callables returning a future. It behaves in the same way as bind(), but avoids returning a nested future.

classmethod Executors.bind(executor, fn)

Bind a synchronous callable to an executor.

If the callable returns a future, consider using flat_bind() instead.

Parameters

• executor (Executor) – an executor

• fn (callable) – any function or callable

Returns

A new callable which, when invoked, will submit fn to executor and return the resulting future.

This returned callable provides the Executors.with_* methods, which may be chained to further customize the behavior of the callable.

Return type

callable

New in version 1.13.0.

classmethod Executors.flat_bind(executor, fn)

Bind an asynchronous callable to an executor.

This convenience method should be used in preference to bind() when the bound callable returns a future, in order to avoid a nested future in the returned value. It is equivalent to:

>>> bind(fn).with_flat_map(lambda future: future)

Parameters

• executor (Executor) – an executor

• fn (callable) – any function or callable which returns a future

Returns

A new callable which, when invoked, will submit fn to executor and return the resulting (flattened) future.

This returned callable provides the Executors.with_* methods, which may be chained to further customize the behavior of the callable.

Return type

callable

New in version 1.16.0.