m4us.interfaces — Message For You Sir! v0.2.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Message For You Sir! v0.2.1 documentation »
- API Documentation »

# `m4us.interfaces`

Provides the interface definitions for all important non-core objects.

## Inheritance Diagram

## Members

interface `IBackplane`

  Extends: `m4us.core.interfaces.ICoroutine`

  Interface that defines backplane coroutines.

  This is an analogue to Kamaelia's `Backplane`, and `SubscribeTo` components.

  A backplane is a coroutine to which one or more publishers can send messages, and to which one or more subscribers can then recieve those messages. The advantage of using a backplane is that the subscribers do not need to know about the publishers and vice versa. The only thing they each need to have is the backplane coroutine through which they are communicating.

  Publishers register themselves by sending an `IRegisterPublisher` message to the backplane's `control` inbox. Similarily, they unregister themselves by sending an `IUnregisterPublisher` message. Publishers are expected to register before sending any messages and unregister before sending any `IShutdown` messages. All this is needed so that the backplane knows when the last publisher is done and can wait until then to shutdown.

  Subscribers to a backplane, just need link to the backplane's `outbox` and `signal` outboxes like any other producer coroutine.

  A backplane will shutdown upon reciept of an `IShutdown` message on it's `control` inbox, but only when there are no registered publishers (i.e. they have all unregistered as part of their shutdown). It will also forward the shutdown message on to all subscribers on it's `signal` outbox, but again, only when there are no registered publishers.

  Raises: | m4us.backplanes.NotRegisteredError -- If a publisher attempts to unregister itself without already being registered. m4us.backplanes.AlreadyRegisteredError -- If a publisher attempts to register itself more than once.

interface `IBackplaneFactory`

  Extends: `m4us.core.interfaces.ICoroutineFactory`

  Interface for callables that return `IBackplane` objects.

  `__call__`(*args, **kwargs)

    Return the desired backplane.

    Parameters: | args (`tuple`) -- Any arguments to pass to the factory callable. kwargs (`dict`) -- Keywords arguments to pass to the factory callable.
    Returns: | The desired backplane coroutine
    Return type: | `IBackplane`

interface `IRegisterPublisher`

  Extends: `m4us.core.interfaces.IMessage`

  Interface for messages that register publishers with backplanes.

  Parameters: | publisher (`object`) -- Messages providing this interface should require a publishing object, specified as a keyword argument.

  See also

  The `IBackplane` interface for details about messages that use this interface.

  `publisher`

    The publisher object to register.

    Type : | `object`

interface `IThreadedCoroutine`

  Extends: `m4us.core.interfaces.ICoroutine`

  Interface that defines threaded coroutines.

  Threaded coroutines work just like regular coroutines, except they run in separate threads. This interface provides an additional method for explicitly starting the thread when it is appropriate.

  The advantage of running a threaded coroutine is that it's methods should return immediately allowing the main thread to continue running without blocking.

  The consequence of this, however, is that a message received from the coroutine is not necessarily the immediate response to the message that was sent in. That is, both sent and received messages are queued up in order and potentially processed at different rates. This is also true for thrown exceptions.

  `start`()

    Start the coroutine thread.

    Raises RuntimeError:
    | If the thread is already running.

interface `IUnregisterPublisher`

  Extends: `m4us.core.interfaces.IMessage`

  Interface for messages that un-register backplane publishers.

  Parameters: | publisher (`object`) -- Messages providing this interface should require a publishing object, specified as a keyword argument.

  See also

  The `IBackplane` interface for details about messages that use this interface.

  `publisher`

    The publisher object to un-register.

    Type : | `object`

### Navigation

- index
- modules |
- next |
- previous |
- Message For You Sir! v0.2.1 documentation »
- API Documentation »