Documentation for pulsar 0.7.2. For development docs, go here.
The Poller interface
Return the handlers for file descriptor fd.
Install event loop waker.
Add a reader handler on file descriptor fd.
Add a writer handler on file descriptor fd.
Add a error handler on file descriptor fd.
Remove the read event on file descriptor fd.
Remove the write event on file descriptor fd.
Remove the error event on file descriptor fd.
Handle events on file descriptor fd.
This method is called by the event loop when new events are triggered.
Unregister file descriptor fd from the poller.
File descriptor for this poller.
a time in the future or None.
The callback to execute in the eventloop
Flag indicating this callback is cancelled.
Attempt to cancel the callback.
A pluggable event loop which conforms with the pep-3156 API.
The event loop is the place where most asynchronous operations are carried out.
The timeout in seconds when polling with epolL, kqueue, select and so forth.
The thread id where this event loop is running. If the event loop is not running this attribute is None.
The Poller for this event loop. If not supplied, the best possible implementation available will be used. On posix system this is epoll or kqueue (Mac OS) or else select.
True if this EventLoop install itself as the event loop of the thread where it is run.
If True this is a CPU bound event loop, otherwise it is an I/O event loop. CPU bound loops can block the loop for considerable amount of time.
Total number of loops.
Run the event loop until nothing left to do or stop() called.
Run the event loop forever.
Run the event loop until a Deferred future is done. Return the future’s result, or raise its exception. If timeout is not None, run it for at most that long; if the future is still not done, raise TimeoutError (but don’t cancel the future).
Stop the loop after the current event loop iteration is complete
True if the loop is running.
Arrange for a callback to be called at a given time when in the future. The time is an absolute time, for relative time check the call_later() method. Returns a TimedCall with a TimedCall.cancel() method that can be used to cancel the call.
Arrange for a callback to be called at a given time.
Each callback will be called exactly once. If two callbacks are scheduled for exactly the same time, it is undefined which will be called first.
Callbacks scheduled in the past are passed on to call_soon() method, so these will be called in the order in which they were registered rather than by time due. This is so you can’t cheat and insert yourself at the front of the ready queue by using a negative time.
Any positional arguments after the callback will be passed to the callback when it is called.
Equivalent to self.call_later(0, callback, *args).
Calls the given callback on the next I/O loop iteration. It is safe to call this method from any thread at any time. Note that this is the only method in EventLoop that makes this guarantee. all other interaction with the EventLoop must be done from that EventLoop‘s thread. It may be used to transfer control from other threads to the EventLoop’s thread.
Arrange to call callback(*args) in an executor.
Return a Deferred called once the callback has finished.
Add a reader callback. Return a Handler instance.
Add a reader callback. Return a Handler instance.
Cancels the current read callback for file descriptor fd, if one is set. A no-op if no callback is currently set for the file descriptor.
Cancels the current write callback for file descriptor fd, if one is set. A no-op if no callback is currently set for the file descriptor.
Add a signal handler.
Whenever signal sig is received, arrange for callback(*args) to be called. Returns a TimedCall handler which can be used to cancel the signal callback.
Remove the signal sig if it was installed and reinstal the default signal handler signal.SIG_DFL.
Creates a stream connection to a given internet host and port.
It is the asynchronous equivalent of socket.create_connection.
a Deferred and its result on success is the (transport, protocol) pair.
If a failure prevents the creation of a successful connection, an appropriate exception will be raised.
Creates a TCP server bound to host and port.
a Deferred whose result will be a list of socket objects which will later be handled by protocol_factory.
The argument should be a socket from the list returned by start_serving() method. The serving loop associated with that socket will be stopped.
Connect sock to the given address.
Returns a Deferred whose result on success will be None.
Accept a connection from a socket sock.
The socket must be in listening mode and bound to an address. Returns a Deferred whose result on success will be a tuple (conn, peer) where conn is a connected non-blocking socket and peer is the peer address.
Wake up the eventloop.
Call a callback every interval seconds. It handles asynchronous results. If an error occur in the callback, the chain is broken and the callback won’t be called anymore.
Same as call_repeatedly() with the only difference that the callback is scheduled at every loop. Installing this callback cause the event loop to poll with a 0 timeout all the times.
Run value in this event loop.
If value is a coroutine, it is run immediately in this event loop.
This section describes the asynchronous discover functions which are used throughout the library to access if objects are asynchronous or not. There are two important functions: maybe_async() and maybe_failure() for asynchronous exceptions.
Handle a possible asynchronous value.
Convert value into a Failure if it is a stack trace or an exception, otherwise returns value.
a Failure or the original value.
A collection of asynchronous utilities which facilitates manipulation and interaction with asynchronous components.
A decorator for asynchronous components.
It convert the return value of the callable it decorates into a Deferred via the maybe_async() function. The return value is always a Deferred (unless get_result is True), and the function never throws.
Check the Asynchronous utilities tutorial for detailed discussion and examples.
@async() def myfunction(...): ...
When invoked, myfunction it returns a Deferred. For example:
@async() def simple(): return 1 @async() def simple_error(): raise ValueError('Kaput!') @async() def simple_coro(): result = yield ... ...
>>> d = simple() >>> d Deferred (done) >>> d.result 1 >>> d = simple_error() >>> d Deferred (done) >>> d.result Failure: Traceback (most recent call last): File "...pulsarsync\defer.py", line 260, in call result = callable(*args, **kwargs) File ... raise ValueError('Kaput!') ValueError: Kaput!
The asynchronous equivalent of time.sleep(timeout). Use this function within a coroutine when you need to resume the coroutine after timeout seconds. For example:
... yield async_sleep(2) ...
This function returns a Deferred called back in timeout seconds with the timeout value.
The asynchronous equivalent of while while_clause(*args):
Use this function within a coroutine when you need to wait while_clause to be satisfied.
The main class of pulsar asynchronous engine. It is a callback which will be put off until later. It conforms with the tulip.Future interface with an implementation similar to the twisted.defer.Deferred class.
returns self so that other methods can be concatenated.
pep-3156 API method, it cancel the deferred and schedule callbacks. If the deferred is waiting for another Deferred, forward the cancellation to that one. If the Deferred is already done(), it does nothing.
|Parameters:||msg – Optional message to pass to the when the CancelledError is initialised.|
Retrieve the result is ready.
If not raise InvalidStateError.
Add a callback, and an optional errback.
Add the two functions to the list of callbaks. Both of them take at most one argument, the result passed to the callback() method.
If the errback callable is provided it will be called when an exception occurs.
Equivalent to self.add_callback(callback, callback).
Run registered callbacks with the given result. This can only be run once. Later calls to this will raise InvalidStateError. If further callbacks are added after this point, add_callback() will run the callbacks immediately.
|Returns:||the result input parameter|
Chain another deferred to this Deferred callbacks.
This method adds callbacks to this Deferred to call deferred‘s callback or errback, as appropriate.
|Parameters:||deferred – a Deferred which will partecipate in the callback chain of this Deferred.|
Add another deferred to this Deferred callbacks.
|Parameters:||deferred – Optional Deferred to call back when this Deferred receives the result or the exception. If not supplied a new Deferred is created.|
|Returns:||The deferred passed as parameter or the new deferred created.|
This method adds callbacks to this Deferred to call deferred‘s callback or errback, as appropriate. It is a shorthand way of performing the following:
def cbk(result): deferred.callback(result) return result self.add_both(cbk)
When you use then on deferred d1:
d2 = d1.then()
you obtains a new deferred d2 which receives the callback when d1 has received the callback, with the following properties:
This method can be used instead of add_callback() if a bright new deferred is required:
d2 = d1.then().add_callback(...)
A :class:1Deferred` for a collection of asynchronous objects.
The collection can be either a list or a dict.
When True and at least one value of the result collections is a Failure, the callback will receive the failure rather than the collection of results.
The type of multi-deferred. Either a list or a Mapping.
Total number of seconds taken to obtain the result.
A Task is a Deferred which consumes a coroutine. The callback will occur once the coroutine has finished (when it raises StopIteration), or an unhandled exception occurs. Instances of Task are never initialised directly, they are created by the maybe_async() function when a generator is passed as argument.
The asynchronous equivalent of python Exception.
It has several useful methods and features which facilitates logging, and throwing exceptions.
The exception as a three elements tuple (errorType, errvalue, traceback) occured during the execution of a Deferred.
Check if the error was logged. It can be used for switching off logging for certain errors by setting:
failure.logged = True
The python Exception instance.
Raises the exception from the exc_info.
|Parameters:||gen – Optional generator. If provided the exception is throw into the generator via the gen.throw method.|
Without gen, this method is used when interacting with libraries supporting both synchronous and asynchronous flow controls.
Logging for a given failure occurs once only. To suppress logging for a given failure set logged to True of invoke the mute() method. Returns self so that this method can easily be added as an error back to perform logging and propagate the failure. For example:
.add_errback(lambda failure: failure.log())
Mute logging and return self.
The EventHandler class is for creating objects with events. These events can occur once only during the life of an EventHandler or can occur several times. Check the event dispatching tutorial for an overview.
An event managed by an EventHandler class.
Boolean indicating if this event is silenced.
To silence an event one uses the EventHandler.silence_event() method.
Check if this event has fired.
This only make sense for one time events.
Fire this event.
This method is called by the EventHandler.fire_event() method.
A Mixin for handling events.
Event names which occur once only.
Event names which occur several times.
The dictionary of all events.
Register a callback with event.
The callback must be a callable accepting one parameter only, the instance firing the event or the first positional argument passed to the fire_event() method.
Register all known events found in events key-valued parameters.
Dispatches arg or self to event name listeners.
for one-time events, it returns whatever is returned by the event handler. For many times events it returns nothing.
Silence event name.
This causes the event not to fire at the fire_event() method is invoked with the event name.
Chain the event name from other.
Asynchronous FIFO queue.
Integer representing the upper bound limit on the number of items that can be placed in the queue.
If maxsize is less than or equal to zero, there is no upper bound.
The event loop running the queue
Size of the queue.
Put an item in the queue.
If you yield from put() and timeout is None (the default), wait until a item is added to the queue. Otherwise raise Full if no slots is available before timeout.
a Deferred resulting in None if wait is True, otherwise None.
Put an item into the queue..
Put an item if a slot is immediately available, otherwise raise Full. Equivalent to self.put(item, wait=False).
Remove and return an item from the queue.
If you yield from get() and timeout is None (the default), wait until a item is available. Otherwise raise Empty if no item is available before timeout.
a Deferred resulting in the item removed form the queue if wait is True, otherwise the item removed from the queue.
Remove and return an item from the queue.
Return an item if one is immediately available otherwise raise Empty. Equivalent to self.get(wait=False).