m4us.backplanes — Message For You Sir! v0.1.1 documentation

### Navigation

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

# `m4us.backplanes`

Provides backplanes for publisher/subscriber interactions.

## Inheritance Diagram

## Members

exception `AlreadyRegisteredError`(message=None, **kwargs)

  Bases: `m4us.core.exceptions.M4USException`

  Raised when a publisher has attempted to register more than once.

  The default message requires a `publisher` attribute or keyword argument.

  See also

  The `IBackplane` interface for details about this exeption's usage.

exception `NotRegisteredError`(message=None, **kwargs)

  Bases: `m4us.core.exceptions.M4USException`

  Raised when a publisher has not been registered by a backplane.

  The default message requires a `publisher` attribute or keyword argument.

  See also

  The `IBackplane` interface for details about this exeption's usage.

class `Backplane`(**kwargs)

  Bases: `m4us.core.components.Component`

  Backplane that lets publishers send messages to subscribers.

  To create a backplane, just instantiate this class and store the resulting component. Then make the backplane available for import by any publishing and subscribing modules.

  To publish messages to the backplane, use the `publish_to()` function.

  To subscribe to a backplane, just link to the backplane's `outbox` and `signal` outboxes like any other publisher coroutine.

  Implements : | `IBackplane`
  Provides : | `IBackplaneFactory`

  See also

  The `IBackplane` interface for more details on backplanes.

class `Publisher`(**kwargs)

  Bases: `m4us.core.components.Component`

  Component that registers with a backplane before sending messages.

  `IBackplane` coroutines expect that registration and un-registration messages will be sent by publishers before and after usage. This component handles those actions transparently. Just link this component's `outbox` and `signal` outboxes to the backplane's `inbox` and `control` inboxes.

  This is usually all handled automatically by the `publish_to()` function.

  Messages sent to this class will be forwarded back out, but only after an `IRegisterPublisher` message is emitted first. Similarily, before an `IShutdown` message is forwarded on, an `IUnregisterPublisher` message is emitted first.

  Implements : | `ICoroutine` and `INotLazy`
  Provides : | `ICoroutineFactory`

  See also

  The `publish_to()` function for the normal way to publish to a backplane.

  See also

  The `RegisterPublisher` and `UnregisterPublisher` classes as examples of concrete classes that publishers can use for registration and unregistration.

class `RegisterPublisher`(**kwargs)

  Bases: `m4us.core.messages.Message`

  Message for registering publishers with backplanes.

  Parameters: | publisher (`object`) -- The publishing object, specified as a keyword argument.
  Implements : | `IRegisterPublisher`
  Provides : | `IMessageFactory`

  See also

  The `Publisher` component and the `IBackplane` interface for details about how this message is used.

  `publisher`

    The publisher object to register.

    Type : | any

class `UnregisterPublisher`(**kwargs)

  Bases: `m4us.backplanes.RegisterPublisher`

  Message for unregistering publishers with backplanes.

  Parameters: | publisher (`object`) -- The publishing object, specified as a keyword argument.
  Implements : | `IUnregisterPublisher`
  Provides : | `IMessageFactory`

  See also

  The `Publisher` component and the `IBackplane` interface for details about how this message is used.

  `publisher`

    The publisher object to unregister.

    Type : | any

`publish_to`(backplane)

  Return a component knows how to publish messages to a backplane.

  This is just a convenience function that returns a `Pipeline` of a `Publisher` component, the given `Backplane` object and a `null_sink()` coroutine.

  Parameters: | backplane (`IBackplane`) -- The backplane object to which to publish messages.
  Returns: | A container component that will publish all sent messages to the given backplane.
  Return type: | `Pipeline`

  Note

  Since this function returns an `IContainer` component, remember to register it's coroutines and links with the scheduler and post office, or include it in another container.

### Navigation

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