Documentation for pulsar 0.9.2. For development docs, go here.

Asynchonous API

Pulsar asynchronous api is built on top of the new python asyncio module, therefore pulsar.Future class is an alias for asyncio.Future.

However, pulsar can run on python 2.7 and 3.3+ using the same code base. To achieve this, pulsar uses a specialised asyncio.Task class with the following features:

  • works with both yield and yield from
  • tolerant of synchronous values

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

_logger

Optional logger instance, used by the logger attribute

logger

The logger for this object.

It is either the _logger or the logger of the _loop

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:

a Future which results in a Bench object if successful

The usage is simple:

>>> b = self.timeit('asyncmethod', 100)
class pulsar.async.futures.Bench(times, loop=None)[source]

Execute a given number of asynchronous requests and wait for results.

start = None

The time() when the execution starts

finish = None

The time() when the execution finishes

result = ()

Tuple of results

taken

The total time taken for execution

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

The coroutine is wrapped with the yield_from() function.

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, a Future.

Parameters:
  • value – the value to convert to an asynchronous instance if it needs to.
  • loop – optional EventLoop.
Returns:

a Future or a synchronous value.

Chain Future

pulsar.async.futures.chain_future(future, callback=None, errback=None, next=None, timeout=None)[source]

Chain a Future to an existing future.

This function chain the next future to an existing future. When the input future receive a result the optional callback is executed and its result set as the results of next. If an exception occurs the optional errback is executed.

Parameters:
  • future – the original Future (can be a coroutine)
  • callback – optional callback to execute on the result of future
  • errback – optional callback to execute on the exception of future
  • next – optional Future to chain. If not provided a new future is created
  • timeout – optional timeout to set on next
Returns:

the future next

Coroutine return

pulsar.async.futures.coroutine_return(*value)[source]

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.

Run in loop

pulsar.async.futures.run_in_loop(_loop, callable, *args, **kwargs)[source]

Run callable in the event loop thread, thread safe.

Parameters:_loop – The event loop where callable is run
Returns:a Future

Yield From

pulsar.async.futures.yield_from(coro, timeout=None, loop=None)[source]

Wraps a coroutine by yielding values wrapped with the From function.

Executor

Classes used by pulsar to create event loop executors. For more information on how to use an event loop executor check the asyncio documentation and pulsar CPU based actors.

Thread pool

class pulsar.async.threads.ThreadPool(max_workers=None, actor=None, loop=None, maxtasks=None)[source]

A thread pool for an actor.

This pool maintains a group of threads to perform asynchronous tasks via the submit() method.

submit(func, *args, **kwargs)[source]

Equivalent to func(*args, **kwargs).

This method create a new task for function func and adds it to the queue. Return a Future called back once the task has finished.

Queue Event Loop

class pulsar.async.threads.QueueEventLoop(executor, iothreadloop=False, logger=None)[source]

An asyncio event loop which uses IOqueue as its selector.

IOqueue

class pulsar.async.threads.IOqueue(executor)[source]

A selector based on a distributed queue

Since there is no way to my knowledge to wake up the queue while getting an item from the task queue, the timeout cannot be larger than a small number which by default is 0.5 seconds.



Table Of Contents

Previous topic

API

Next topic

Actors API

This Page