August'24: Kamaelia is in maintenance mode and will recieve periodic updates, about twice a year,
primarily targeted around Python 3 and ecosystem compatibility.
PRs are always welcome. Latest Release: 1.14.32 (2024/3/24)
Axon.Linkage.py
Version: Axon 1.0
TODO: test suite doesn't emit
API docs quite right
Components only have input & output boxes. For data to get from a
producer (eg a file reader) to a consumer (eg an encryption component)
then the output of one component, the source component, must be linked
to the input of another component, the sink component.
These need to be registered with a postman (see below) who takes
messages from the outputs and delivers them to the appropriate
destination. This is NOT the usual technique for software messaging.
Normally you create messages, addressed to something specific, and then
the message handler delivers them.
However the method of communication used here is the norm for
_hardware_ systems, and generally results in very pluggable components -
the aim of this system, hence this design approach rather than the
normal. This method of communication is also the norm for one form of
software system - unix shell scripting - something that has shown itself
time and again to be used in ways the inventors of programs/components
never envisioned.
Pydoc Style
Documentation
class linkage(Axon.Axon.AxonObject)
Linkage - Since components can only talk to local interfaces, this
defines the linkages between inputs and outputs of a component. At
present no argument is really optional.
Methods defined here:
__init__(self, source, sink,
sourcebox='outbox', sinkbox='inbox', postoffice=None, passthrough=0,
pipewidth=0, synchronous=None)
- This needs to tag the source/sink boxes as synchronous, to get
component to go "BANG" if writing to a blocked
__str__(self)
dataToMove(self)
moveData(self, force=False)
moveDataWithCheck(self)
setShowTransit(self,
showtransit)
setSynchronous(self,
pipewidth=None)
sinkPair(self)
sourcePair(self)
Testdoc
Documentation
__init__
- Called with no arguments fails - raises TypeError - must supply
source & sink components...
- Called with source & sink components forms a non-synchronous,
non-passthrough linkage between the source component's outbox to the
sink component's inbox not registered with any postman...
- Providing a pipewidth and synchronous flag set to false is an error.
Raises an exception.
- Providing a pipewidth automatically changes the source/sink boxes to
being synchronised - with a maximum number of items in transit. (Clearly
just stored by the object during initialisation). ttbw
- The synchronous flag is stored to note whether the linkage limits
deliveries based on whether the recipient (sink) box has space to
recieve data. Source & Sink boxes are changed to be synchronous if
they were not originally defined to be so. ttbw
- When created with a defined postoffice/postman, the linkage
registers itself with that postman.
- called with both source/sink in/outboxes in addition to min-args
forms a linkage between the specified source/sink boxes.
- called with passthrough set to 0 results in a standard
non-passthrough outbox to inbox linkage.
- called with passthrough set to 1 means the source and sink boxes are
both inboxes. This means the linkage is passthrough-inbound (normally
from the inbox of a wrapper component to the inbox of a
worker/sub-component).
- called with passthrough set to 2 means the source and sink boxes are
both outboxes. This means the linkage is passthrough-outbound (normally
from the outbox of a worker/sub-component to the outbox of a wrapper
component ). ttbw
__str__
- Returns a string that indicates the link source and sink components
and boxes. Precise formatting is checked.
dataToMove
- Checks whether the source has any data available on it that needs
moving to the sink.
- Checks whether the source has any data available on it that needs
moving to the sink. Passthrough inbox->inbox test.
- Checks whether the source outbox has any data available on it. This
works on normal linkages.
moveData
- .
- .
- Moves data from source to sink. Forces despite full pipe.
- Moves data from source to sink. Forces move despite pipewidth.
- Moves data from source to sink. One item is moved if there is room
in the sink box. IndexError is thrown if source box is empty so check
with dataToMove before calling unless you know there is an item
available.
- Moves data from source to sink. One item is moved if there is room
in the sink box. IndexError is thrown if source box is empty so check
with dataToMove before calling unless you know there is an item
available.
- Moves data from source to sink. One item is moved if there is room
in the sink box. noSpaceInBox is thrown if _deliver is called and source
box is full.
- Moves data from source to sink. One item is moved if there is room
in the sink box. noSpaceInBox is thrown if source box is full.
setSynchronous
- Makes a linkage synchronous with its current pipewidth, will default
to 1. Calls _synchronised Box on each component so that the boxes are
setup correctly.
- Makes a linkage synchronous with its the argument as the
pipewidth.
Michael, December 2004