circuits.core.manager module

This module defines the Manager class.

exception circuits.core.manager.UnregistrableError

Bases: Exception

Raised if a component cannot be registered as child.

exception circuits.core.manager.TimeoutError

Bases: Exception

Raised if wait event timeout occurred

class circuits.core.manager.CallValue(value)

Bases: object

class circuits.core.manager.ExceptionWrapper(exception)

Bases: object

extract()
class circuits.core.manager.Sleep(seconds)

Bases: object

property expired
property task
circuits.core.manager.sleep(seconds)

Delay execution of a coroutine for a given number of seconds. The argument may be a floating point number for subsecond precision.

class circuits.core.manager.Manager(*args, **kwargs)

Bases: object

The manager class has two roles. As a base class for component implementation, it provides methods for event and handler management. The method fireEvent() appends a new event at the end of the event queue for later execution. waitEvent() suspends the execution of a handler until all handlers for a given event have been invoked. callEvent() combines the last two methods in a single method.

The methods addHandler() and removeHandler() allow handlers for events to be added and removed dynamically. (The more common way to register a handler is to use the handler() decorator or derive the class from Component.)

In its second role, the Manager takes the role of the event executor. Every component hierarchy has a root component that maintains a queue of events. Firing an event effectively means appending it to the event queue maintained by the root manager. The flush() method removes all pending events from the queue and, for each event, invokes all the handlers. Usually, flush() is indirectly invoked by run().

The manager optionally provides information about the execution of events as automatically generated events. If an Event has its success attribute set to True, the manager fires a Success event if all handlers have been executed without error. Note that this event will be enqueued (and dispatched) immediately after the events that have been fired by the event’s handlers. So the success event indicates both the successful invocation of all handlers for the event and the processing of the immediate follow-up events fired by those handlers.

Sometimes it is not sufficient to know that an event and its immediate follow-up events have been processed. Rather, it is important to know when all state changes triggered by an event, directly or indirectly, have been performed. This also includes the processing of events that have been fired when invoking the handlers for the follow-up events and the processing of events that have again been fired by those handlers and so on. The completion of the processing of an event and all its direct or indirect follow-up events may be indicated by a Complete event. This event is generated by the manager if Event has its complete attribute set to True.

Apart from the event queue, the root manager also maintains a list of tasks, actually Python generators, that are updated when the event queue has been flushed.

initializes x; see x.__class__.__doc__ for signature

property name

Return the name of this Component/Manager

property running

Return the running state of this Component/Manager

property pid

Return the process id of this Component/Manager

getHandlers(event, channel, **kwargs)
addHandler(f)
removeHandler(method, event=None)
registerChild(component)
unregisterChild(component)
fireEvent(event, *channels, **kwargs)

Fire an event into the system.

Parameters

  • event – The event that is to be fired.

  • channels – The channels that this event is delivered on. If no channels are specified, the event is delivered to the channels found in the event’s channel attribute. If this attribute is not set, the event is delivered to the firing component’s channel. And eventually, when set neither, the event is delivered on all channels (“*”).

fire(event, *channels, **kwargs)

Fire an event into the system.

Parameters

  • event – The event that is to be fired.

  • channels – The channels that this event is delivered on. If no channels are specified, the event is delivered to the channels found in the event’s channel attribute. If this attribute is not set, the event is delivered to the firing component’s channel. And eventually, when set neither, the event is delivered on all channels (“*”).

registerTask(g)
unregisterTask(g)
waitEvent(event, *channels, **kwargs)
wait(event, *channels, **kwargs)
callEvent(event, *channels, **kwargs)

Fire the given event to the specified channels and suspend execution until it has been dispatched. This method may only be invoked as argument to a yield on the top execution level of a handler (e.g. “yield self.callEvent(event)”). It effectively creates and returns a generator that will be invoked by the main loop until the event has been dispatched (see circuits.core.handlers.handler()).

call(event, *channels, **kwargs)

Fire the given event to the specified channels and suspend execution until it has been dispatched. This method may only be invoked as argument to a yield on the top execution level of a handler (e.g. “yield self.callEvent(event)”). It effectively creates and returns a generator that will be invoked by the main loop until the event has been dispatched (see circuits.core.handlers.handler()).

flushEvents()

Flush all Events in the Event Queue. If called on a manager that is not the root of an object hierarchy, the invocation is delegated to the root manager.

flush()

Flush all Events in the Event Queue. If called on a manager that is not the root of an object hierarchy, the invocation is delegated to the root manager.

start(process=False, link=None)

Start a new thread or process that invokes this manager’s run() method. The invocation of this method returns immediately after the task or process has been started.

join()
stop(code=None)

Stop this manager. Invoking this method causes an invocation of run() to return.

processTask(event, task, parent=None)
tick(timeout=-1)

Execute all possible actions once. Process all registered tasks and flush the event queue. If the application is running fire a GenerateEvents to get new events from sources.

This method is usually invoked from run(). It may also be used to build an application specific main loop.

Parameters

timeout (float, measuring seconds) – the maximum waiting time spent in this method. If negative, the method may block until at least one action has been taken.

run(socket=None)

Run this manager. The method fires the Started event and then continuously calls tick().

The method returns when the manager’s stop() method is invoked.

If invoked by a programs main thread, a signal handler for the INT and TERM signals is installed. This handler fires the corresponding Signal events and then calls stop() for the manager.