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 (collections.Sequence) -- Any arguments to pass to the factory callable.
• kwargs (collections.Mapping) -- 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 -- 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.

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 exceptions.RuntimeError:  If the thread is already running.

interface IUnregisterPublisher

Extends: m4us.core.interfaces.IMessage

Interface for messages that un-register backplane publishers.

Parameters:publisher -- 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.