m4us.core.containers — Message For You Sir! v0.1.1 documentation

### Navigation

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

# `m4us.core.containers`

Provides components that can contain and link other components.

Containers are components that contain other components and coroutines, linking them in various ways. These objects make it convenient to group coroutines together to make larger reusable components. The coroutines contained within containers can be linked not only to each other, but to the containers as well, allowing the containers externally to act like any other components.

## Inheritance Diagram

## Members

class `Graphline`(*links, **kwargs)

  Bases: `m4us.core.components.Component`

  Container component of coroutines with fully configurable links.

  This corresponds to Kamaelia's `Graphline` class.

  This class is useful for grouping several coroutines together, while still being able to specify special (i.e. non-standard) links among them. Where the `Pipeline` class provides a strait linear linkage between it's coroutines, this class allows you to specify your own links as required.

  Only the links need to be specified. The unique collection of coroutines will be automatically extracted from them.

  Additionally, if a source or sink is specified as `'self'`, then a link will be created with the `Graphline` instance. This allows messages sent to the `Graphline` instance to be forwarded on to the appropriate child coroutine and messages from a child to be sent out as the output from the `Graphline`. Note, however, that unlike regular links, when using `'self'`, links should be outbox to outbox or inbox to inbox. Kamaelia calls these types of links pass-through linkages.

  Example:

      >>> graphline = Graphline(
      ...   ('self', 'inbox', coroutine1, 'inbox'),
      ...   ('self', 'control', coroutine1, 'control'),
      ...   (coroutine1, 'outbox', coroutine2, 'inbox'),
      ...   (coroutine1, 'signal', coroutine2, 'control'),
      ...   (coroutine1, 'outbox', coroutine3, 'inbox'),
      ...   (coroutine1, 'signal', coroutine3, 'control'),
      ...   (coroutine2, 'outbox', 'self', 'outbox'),
      ...   (coroutine2, 'signal', 'self', 'signal'),
      ...   (coroutine3, 'outbox', 'self', 'outbox'),
      ...   (coroutine3, 'signal', 'self', 'signal'),
      ... )
      >>> scheduler.add(*graphline.coroutines)
      >>> post_office.link(*graphline.links)

  In this example, messages sent to graphline will be forwarded on to coroutine1. Messages from coroutine1 will be sent to both coroutine2 and coroutine3. And messages from both coroutine2 and coroutine3 will be forwarded out from graphline. This is a good example of non-standard links.

  Assuming there is a producer and a consumer connected to either side of the graphline, then visually, the above example looks like this:

  Parameters: | links (`tuple` of 4-`tuple`s) -- The links and coroutines to contain. Each link should be in the form of `(source, outbox, sink, inbox)`. kwargs (`dict`) -- Any keyword arguments will be set as attributes on the instance.
  Raises m4us.core.exceptions.InvalidLinkError:
  | If an invalid link involving the `Graphline`'s mailboxes is attempted.
  Implements : | `ICoroutine` and `IContainer`
  Provides : | `ICoroutineFactory` and `IContainerFactory`

  See also

  The `ICoroutine` and `IContainer` interfaces for details on the methods and attributes provided by instances of this class.

class `Pipeline`(first_coroutine, second_coroutine, *other_coroutines, **kwargs)

  Bases: `m4us.core.containers.Graphline`

  Container component of coroutines that links them in a pipeline.

  This corresponds to Kamaelia's `Pipeline` class.

  A pipeline consists of chaining each of the given coroutines together in order such that the `outbox` and `signal` outboxes of each coroutine are linked to the `inbox` and `control` inboxes of the next one.

  Additionally, the `Pipeline`'s `inbox` and `control` inboxes are linked to the first coroutine's `inbox` and `control` inboxes. Similarily, the `Pipeline`'s `outbox` and `signal` outboxes are linked to the last coroutine's `outbox` and `signal` outboxes. This means that the pipeline can be treated like any other coroutine, responding to incomming messages and emitting outgoing messages.

  Example:

      >>> pipeline = Pipeline(coroutine1, coroutine2, coroutine3)
      >>> scheduler.add(*pipeline.coroutines)
      >>> post_office.link(*pipeline.links)

  In this example, messages sent to pipeline will be forwarded on to coroutine1, who's messages will be sent to coroutine2, who's messages will be sent to coroutine3, who's messages will be forwarded out of pipeline.

  Assuming there is a producer and a consumer connected to either side of the pipeline, then visually, the above example looks like this:

  Parameters: | first_coroutine (`ICoroutine`) -- The first coroutine in the pipeline. It will receive incomming messages to the pipeline. other_coroutines (`tuple` of `ICoroutine`s) -- Any other coroutines in the pipeline, in order. Messages emmitted by the last one will be emitted by the pipeline. kwargs (`dict`) -- Like other components, any given keyword arguments will be set as instance attributes.
  Implements : | `ICoroutine` and `IContainer`
  Provides : | `ICoroutineFactory` and `IContainerFactory`

  See also

  The `ICoroutine` and `IContainer` interfaces for details on the methods and attributes provided by instances of this class.

### Navigation

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