pants.engine

Asynchronous event processing and timer scheduling.

Pants applications are powered by instances of the Engine class. An Engine instance keeps track of active channels, continuously checks them for new events and raises those events on the channel when they occur. The Engine class also provides the timer functionality which allows callable objects to be invoked after some delay without blocking the process.

Engines

Pants’ engines are very simple to use. After you have finished initializing your application, simply call start() to enter the blocking event loop. stop() may be called at any time to cause a graceful exit from the event loop. If your application has a pre-existing event loop you can call the poll() method on each iteration of that loop rather than using start() and stop(). Ideally, poll() should be called many times each second to ensure that events are processed efficiently and timers are executed on schedule.

The global engine instance is returned by the instance() classmethod. It is not required that you use the global engine instance, but it is strongly recommended. By default, new channels are automatically added to the global engine when they are created. Channels can be added to a specific engine by passing the engine instance as a keyword argument to the channel’s constructor. If a Server is added to a non-default engine, any connections it accepts will also be added to that engine.

Timers

In addition to managing channels, Pants’ engines can also schedule timers. Timers are callable objects that get invoked at some point in the future. Pants has four types of timers: callbacks, loops, deferreds and cycles. Callbacks and loops are executed each time poll() is called - callbacks are executed once while loops are executed repeatedly. Deferreds and cycles are executed after a delay specified in seconds - deferreds are executed once while cycles are executed repeatedly.

Engine has methods for creating each of the four types of timers: callback(), loop(), defer() and cycle(). Each of these methods is passed a callable to execute as well as any number of positional and keyword arguments:

engine.callback(my_callable, 1, 2, foo='bar')

The timer methods all return a callable object which can be used to cancel the execution of the timer:

cancel_cycle = engine.cycle(10.0, my_callable)
cancel_cycle()

Any object references passed to a timer method will be retained in memory until the timer has finished executing or is cancelled. Be aware of this when writing code, as it may cause unexpected behaviors should you fail to take these references into account. Timers rely on their engine for scheduling and execution. For best results, you should either schedule timers while your engine is running or start your engine immediately after scheduling your timers.

Pollers

By default, Pants’ engines support the epoll, kqueue and select polling methods. The most appropriate polling method is selected based on the platform on which Pants is running. Advanced users may wish to use a different polling method. This can be done by defining a custom poller class and passing an instance of it to the Engine constructor. Interested users should review the source code for an understanding of how these classes are defined and used.

Engine

class pants.engine.Engine(poller=None)

The asynchronous engine class.

An engine object is responsible for passing I/O events to active channels and running timers asynchronously. Depending on OS support, the engine will use either the epoll(), kqueue() or select() system call to detect events on active channels. It is possible to force the engine to use a particular polling method, but this is not recommended.

Most applications will use the global engine object, which can be accessed using instance(), however it is also possible to create and use multiple instances of Engine in your application.

An engine can either provide the main loop for your application (see start() and stop()), or its functionality can be integrated into a pre-existing main loop (see poll()).

Argument	Description
poller	Optional. A specific polling object for the engine to use.

callback(function, *args, **kwargs)

Schedule a callback.

A callback is a function (or other callable) that is executed the next time poll() is called - in other words, on the next iteration of the main loop.

Returns a callable which can be used to cancel the callback.

Argument	Description
function	The callable to be executed when the callback is run.
args	The positional arguments to be passed to the callable.
kwargs	The keyword arguments to be passed to the callable.

cycle(interval, function, *args, **kwargs)

Schedule a cycle.

A cycle is a deferred that is continuously rescheduled. It will be run at regular intervals.

Returns a callable which can be used to cancel the cycle.

Argument	Description
interval	The interval, in seconds, at which the cycle should be run.
function	The callable to be executed when the cycle is run.
args	The positional arguments to be passed to the callable.
kwargs	The keyword arguments to be passed to the callable.

defer(delay, function, *args, **kwargs)

Schedule a deferred.

A deferred is a function (or other callable) that is executed after a certain amount of time has passed.

Returns a callable which can be used to cancel the deferred.

Argument	Description
delay	The delay, in seconds, after which the deferred should be run.
function	The callable to be executed when the deferred is run.
args	The positional arguments to be passed to the callable.
kwargs	The keyword arguments to be passed to the callable.

classmethod instance()

Returns the global engine object.

loop(function, *args, **kwargs)

Schedule a loop.

A loop is a callback that is continuously rescheduled. It will be executed every time poll() is called - in other words, on each iteraton of the main loop.

Returns a callable which can be used to cancel the loop.

Argument	Description
function	The callable to be executed when the loop is run.
args	The positional arguments to be passed to the callable.
kwargs	The keyword arguments to be passed to the callable.

poll(poll_timeout)

Poll the engine.

Updates timers and processes I/O events on all active channels. If your application has a pre-existing main loop, call poll() on each iteration of that loop, otherwise, see start().

Argument	Description
poll_timeout	The timeout to be passed to the polling object.

start(poll_timeout=0.2)

Start the engine.

Initialises and continuously polls the engine until either stop() is called or an uncaught Exception is raised. start() should be called after your asynchronous application has been fully initialised. For applications with a pre-existing main loop, see poll().

Argument	Description
poll_timeout	Optional. The timeout to pass to poll().

stop()

Stop the engine.

If start() has been called, calling stop() will cause the engine to cease polling and shut down on the next iteration of the main loop.