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.register(*graphline.coroutines)
>>> post_office.register(*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 (collections.Sequence) -- The links and coroutines to contain. Each link should be in the form of (source, outbox, sink, inbox).
• kwargs (collections.Mapping) -- 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 :

m4us.core.interfaces.ICoroutine and m4us.core.interfaces.IContainer

Provides :

m4us.core.interfaces.ICoroutineFactory and m4us.core.interfaces.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.register(*pipeline.coroutines)
>>> post_office.register(*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 (m4us.core.interfaces.ICoroutine) -- The first coroutine in the pipeline. It will receive incomming messages to the pipeline.
• second_coroutine (m4us.core.interfaces.ICoroutine) -- The second coroutine in the pipeline. It will receive incomming messages to the pipeline.
• other_coroutines (collections.Sequence) -- Any other coroutines in the pipeline, in order. Messages emmitted by the last one will be emitted by the pipeline.
• kwargs (collections.Mapping) -- Like other components, any given keyword arguments will be set as instance attributes.

Implements :

m4us.core.interfaces.ICoroutine and m4us.core.interfaces.IContainer

Provides :

m4us.core.interfaces.ICoroutineFactory and m4us.core.interfaces.IContainerFactory

See also

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