Asynchronous API¶
Pulsar asynchronous api is built on top of the new python asyncio
module.
Async object interface¶
This small class is the default interface for asynchronous objects. It is provided mainly for documentation purposes.
-
class
pulsar.async.futures.
AsyncObject
[source]¶ Interface for async objects
-
_loop
¶ The event loop associated with this object
-
debug
¶ True when in debug mode
-
timeit
(method, times, *args, **kwargs)[source]¶ Useful utility for benchmarking an asynchronous
method
.Parameters: - method – the name of the
method
to execute - times – number of times to execute the
method
- args – positional arguments to pass to the
method
- kwargs – key-valued arguments to pass to the
method
Returns: The usage is simple:
>>> b = self.timeit('asyncmethod', 100)
- method – the name of the
-
Async Utilities¶
A collection of asynchronous utilities which facilitates manipulation and interaction with asynchronous components.
task¶
-
pulsar.async.futures.
task
(function)[source]¶ Thread-safe decorator to run a
function
in an event loop.Parameters: function – a callable which can return coroutines, asyncio.Future
or synchronous data. Can be a method of an async object, in which case the loop is given by the object_loop
attribute.Returns: a Future
Maybe Async¶
-
pulsar.async.futures.
maybe_async
(value, loop=None)[source]¶ Handle a possible asynchronous
value
.Return an asynchronous instance only if
value
is a generator, aFuture
.Parameters: - value – the value to convert to an asynchronous instance if it needs to.
- loop – optional
EventLoop
.
Returns: a
Future
or a synchronousvalue
.
Chain Future¶
-
pulsar.async.futures.
chain_future
(future, callback=None, errback=None, next=None)[source]¶ Chain a
Future
to an existingfuture
.This function chain the
next
future to an existingfuture
. When the inputfuture
receive a result the optionalcallback
is executed and its result set as the results ofnext
. If an exception occurs the optionalerrback
is executed.Parameters: Returns: the future
next
Multi Async¶
-
pulsar.async.futures.
multi_async
(data=None, loop=None, type=None, raise_on_error=True)¶ Handle several futures at once. Thread safe.
Async While¶
-
pulsar.async.futures.
async_while
(timeout, while_clause, *args)[source]¶ The asynchronous equivalent of
while while_clause(*args):
Use this function within a coroutine when you need to wait
while_clause
to be satisfied.Parameters: - timeout – a timeout in seconds after which this function stop.
- while_clause – while clause callable.
- args – optional arguments to pass to the
while_clause
callable.
Returns: A
Future
.
Lock¶
-
class
pulsar.async.lock.
LockBase
(name, *, loop=None, timeout=None, blocking=True)[source]¶ A asynchronous locking primitive associated to a given name.
An asynchronous lock is in one of two states, ‘locked’ or ‘unlocked’. It is created in the unlocked state. It has two basic methods,
acquire()
andrelease. When the state is unlocked, :meth:()
.acquire` changes the state to locked and returns immediately.When the state is locked,
acquire()
wait until a call torelease()
changes it to unlocked, then theacquire()
call resets it to locked and returns.-
blocking
¶ The time to wait for the lock to be free when acquiring it. When False it does not block, when True it blocks forever, when a positive number blocks for
blocking
seconds.
-
timeout
¶ Free the lock after timeout seconds. If timeout is None (default) does not free the lock until
release
is called.
-