circuits.core.manager module¶
This module defines the Manager class.
-
class
circuits.core.manager.
CallValue
(value)¶ Bases:
object
-
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()
andremoveHandler()
allow handlers for events to be added and removed dynamically. (The more common way to register a handler is to use thehandler()
decorator or derive the class fromComponent
.)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. Theflush()
method removes all pending events from the queue and, for each event, invokes all the handlers. Usually,flush()
is indirectly invoked byrun()
.The manager optionally provides information about the execution of events as automatically generated events. If an
Event
has itssuccess
attribute set to True, the manager fires aSuccess
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 ifEvent
has itscomplete
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
-
addHandler
(f)¶
-
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 (seecircuits.core.handlers.handler()
).
-
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 (seecircuits.core.handlers.handler()
).
-
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 (“*”).
-
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 (“*”).
-
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.
-
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.
-
getHandlers
(event, channel, **kwargs)¶
-
join
()¶
-
name
¶ Return the name of this Component/Manager
-
pid
¶ Return the process id of this Component/Manager
-
processTask
(event, task, parent=None)¶
-
registerChild
(component)¶
-
registerTask
(g)¶
-
removeHandler
(method, event=None)¶
-
run
(socket=None)¶ Run this manager. The method fires the
Started
event and then continuously callstick()
.The method returns when the manager’s
stop()
method is invoked.If invoked by a programs main thread, a signal handler for the
INT
andTERM
signals is installed. This handler fires the correspondingSignal
events and then callsstop()
for the manager.
-
running
¶ Return the running state of this Component/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.
-
stop
(code=None)¶ Stop this manager. Invoking this method causes an invocation of
run()
to return.
-
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.
-
unregisterChild
(component)¶
-
unregisterTask
(g)¶
-
wait
(event, *channels, **kwargs)¶
-
waitEvent
(event, *channels, **kwargs)¶
-
-
class
circuits.core.manager.
Sleep
(seconds)¶ Bases:
circuits.six.Iterator
-
expired
¶
-
task
¶
-
-
exception
circuits.core.manager.
TimeoutError
¶ Bases:
exceptions.Exception
Raised if wait event timeout occurred
-
exception
circuits.core.manager.
UnregistrableError
¶ Bases:
exceptions.Exception
Raised if a component cannot be registered as child.
-
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.