# 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.