Axon.Postman.py

Version: Axon 1.0

TODO:Until deprecation, ensure test suite doc strings accurately detail behaviour. (deregister springs to mind as a poor example.)

A postman is a microprocess that knows about linkages, and components, and hence runs concurrently to your components. It can have a number of components & linkages registered with it.

Periodically it checks the sources of the linkages it knows about for messages. If it finds some messages it checks where to deliver them to by looking at the sink of the linkage. Assuming it finds a destination to deliver to, the postmans then delivers the messages to the inbox of the assigned destination component.

The Postman microprocess handles message delivery along linkages between inboxes and outboxes, usually contained in components. There is one postman per component.

Since a postman is a microprocess it runs in parallel with the components it's delivering messages between.

It is highly possible this could result in a race hazard if message queues can grow faster than the postman can deliver them. As a result the system provides Synchronised Boxes as well which have a maximum, enforced capacity which works to prevent this issue - at the expense of extra logic in the client

A Postman can have a debug name - this is to help differentiate between postmen who are delivering things versus those that aren't if problems arise.

Pydoc Style Documentation

class postman(Axon.Microprocess.microprocess)

__init__(self, debugname='')

Constructor. If a debug name is assigned this will be stored as a debugname attribute. Other attributes:

• linkages = list of linkages this postman needs to know about
• things = dict of things this postman has to monitor outboxes on. the index into the dict is the name of the thing monitored, with the value being the thing.
• reverse things = this provides a reverse lookup of things - the index being the id of the component, the value being the name of the component.

__str__(self)

deregister(self, name=None, component=None)

• This deregisters a component from this postman, deleting the reference to the component object. If the reference isn't deleted, the reference count of the object will never reach zero and never be garbage collected.

deregisterlinkage(self, thecomponent=None, thelinkage=None)

• De registers a linkage, based on a provided component. Does not yet de-register based on a user supplied linkage. Simply loops through the linkages, looking for the component being de-registered, and de-registers (deletes) any linkages with that component referenced inside.

domessagedelivery(self)

• Performs the actual message delivery activity. Loops through the *linkages*, scanning their sources, collects messages for delivery to the sinkwbox of the recipient.

islinkageregistered(self, linkage)

• Returns a true value if the linkage given is registered with the postman.

main(self)

register(self, name, component)

• Registers a _named_ component with the postman. These are stored in forward & reverse lookup tables.

registerlinkage(self, thelinkage)

• Registers a linkage with the postman. It's likely this is actually more useful, looking back on this design, since we only deliver things along linkages. (no defaults)

showqueuelengths(self)

• Debugging function really. Takes the debug name of this postman, and appends a textual description of the queue lengths of the inboxes and outboxes of all the components this postman takes from/delivers to. Result is a string, does NOT send output to any output stream. (Did originally, hence "show", is likely to be renamed slightly.)

Testdoc Documentation

__init__

• Called with a debugname which will be stored with ":debug " appended
• Called with no arguments. This is the normal case. <br>

__str__

• Checks the formatted string is of the correct format. <br>

deregister

• Deregisters a component from the postman by name
• Deregisters a component from the postman by name
• Deregisters a component from the postman by name
• Deregisters a component from the postman by name
• Deregisters a component from the postman by name
• Deregisters a component from the postman by name
• Deregisters a component from the postman by name and component

deregisterlinkage

• Tests for a deadlock when a postman deregisters a linkage whose sink is limited in size and full
• Tests for a deadlock when a postman deregisters linkages of a component whose sink is limited in size and full

domessagedelivery

• Checks that linkages with data to move have moveData called. See the AdvancedMockLinkage classes for details.
• Tests for stability when there are no linkages registered.

register

• Registers a component with the postman.

registerlinkage

• Registers a linkage with the Postman

...

Michael, December 2004