The dispatch api: service model & client program mainloop integration

This module provides a means for service models and client programs to co-operate with the main dispatch loop. A default dispatch loop is provided by iterate. The api is defined by IDispatchTarget, IDispatchContext and the the semantics of the before_dispatch and after_dispatch callbacks as ilustrated in the referece iterate function.

iterate may be used directly or as a reference for integrating with foreign main loops.

The dispatch api and the facilities of asycamore.tcpsocket can be used to implement useful client and server programs independently of the servicemodel api (asycamore.servicemodel)

Examples include:

• asycamore.bench.http_processing - client programs for stress testing servers
• asycamore.sclients advanced multiprocess utility to simulate extremely high server load.
• asycamore.httpclient document GET orientated api (but if you are after robust web page retrieval, httplib from the python standard lib, is what you really want)

See asycamore.tcpsocket for the basic primitives necessary for implementing the dispatch targets that form the bridge between the dispatch api and the service model api.

before_dispatch and after_dispatch

iterate and any compatible implementation is required to support these callbacks. They provide the necessary hooks for service models and clients to implement there runtime behaviour. Either callback may be None. The loop control values, along with any others provided by the caller of iterate are passed to the each callback as the dispatchvars parameter. The values include the callbacks them selves and, additionally, count, timeout, and error_in_handler. iterate will honour any changes made to these values. For example, changing or disabling the callbacks. Other than meeting its obligations to keep them updated iterate ignores the values timeout and error_in_handler and simply forwards them as the corresponding arguments to IDispatchContext.dispatch_once

Note that either callback may cause loop termination after N further dispatches by doing dispatchvars['count'] = N. And, immediate termination by simply raising StopIteration.