April 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.


Axon postoffices

A postoffice object looks after linkages. It can create and destroy them and keeps records of what ones currently exist. It hands out linkage objects that can be used as handles to later unlink (remove) the linkage.

THIS IS AN AXON INTERNAL! If you are writing components you do not need to understand this.

Developers wishing to understand how Axon is implemented should read on with interest!

How is this used in Axon?

Every component has its own postoffice. The component's link() and unlink() methods instruct the post office to create and remove linkages.

When a component terminates, it asks its post office to remove any outstanding linkages.

Example usage

Creating a link from an inbox to an outbox; a passthrough link from an inbox to another inbox; and a passthrough link from an outbox to another outbox:

po = postoffice()
c0 = component()
c1 = component()
c2 = component()
c3 = component()

link1 = po.link((c1,"outbox"), (c2,"inbox"))
link2 = po.link((c2,"inbox"), (c3,"inbox"), passthrough=1)
link3 = po.link((c0,"outbox"), (c1,"outbox"), passthrough=2)

Removing one of the linkages; then all linkages involving component c3; then all the rest:




More detail

A postoffice object keeps creates and destroys objects and keeps a record of which ones currently exist.

The linkage object returned when a linkage is created serves only as a handle. It does not form any operation part of the linkage.

Multiple postoffices can (in fact, will) exist in an Axon system. Each looks after its own collection of linkages. A linkage created at one postoffice will not be known to other postoffice objects.

Test documentation

Tests passed:

  • All outboxes in a linkage chain sharing the same destination inbox will experience noSpaceInBox exceptions when and only when the destination inbox becomes full and any of them tries to send to it.
  • Restrict the size of an inbox to 5 and you can send 5 messages to it without error.
  • Send a 6th message to an inbox of size 5 and a noSpaceInBox exception will be thrown.
  • Setting a size limit of None mean the inbox size is unrestricted.
  • A size limited inbox that becomes the final destination in a linkage chain (because a link is broken) causes noSpaceInBox exceptions to be thrown as if it had always been the final destination.
  • A size limited inbox that isn't the final destination in a linkage chain will not cause noSpaceInBox exceptions to be thrown.
  • Setting a size limit then later changing it to None turns off inbox size restrictions.
  • Collecting 3 items from a full inbox and you can put 3 more in before a noSpaceInBox exception is thrown.
  • You can call mycomponent.inboxes[boxname].setSize(n) to set the box size.
  • Simple outox to inbox link, followed by an inbox to inbox passthrough, created in the opposite order
  • Outbox->Inbox->Inbox chain, then 2nd link (passthrough) is deleted
  • Simple outbox to inbox link, preceeded earlier by an outbox to outbox passthough
  • Simple outbox to inbox link
  • Simple outox to inbox link, followed by an inbox to inbox passthrough
  • Simple outbox to inbox link, preceeded later by an outbox to outbox passthough
  • test_BoxAlreadyLinkedToDestinationException (__main__.postoffice_Test)
  • postoffice can be instantiated with a debugger.
  • postoffice can be instantiated with no arguments. Defaults to no debugger or registered linkages.
  • __str__ - Checks the formatted string is of the correct format.
  • test_componentlinksderegisters (__main__.postoffice_Test)
  • test_linkderegisters (__main__.postoffice_Test)
  • test_linkdisengages (__main__.postoffice_Test)
  • test_linkdisengages_inboxinboxpassthrough (__main__.postoffice_Test)
  • test_linkdisengages_outboxoutboxpassthrough (__main__.postoffice_Test)
  • test_linkestablishes (__main__.postoffice_Test)
  • test_linkestablishes_inboxinboxpassthrough (__main__.postoffice_Test)
  • test_linkestablishes_outboxoutboxpassthrough (__main__.postoffice_Test)
  • test_linkregistered (__main__.postoffice_Test)


class postoffice(object)

The post office looks after linkages between postboxes, thereby ensuring deliveries along linkages occur as intended.

There is one post office per component.

A Postoffice can have a debug name - this is to help differentiate between postoffices if problems arise.

Methods defined here

__init__(self[, debugname])

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


Provides a string representation of a postoffice, designed for debugging

deregisterlinkage(self[, thecomponent][, thelinkage])

Stub for legacy

islinkageregistered(self, linkage)

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

link(self, source, sink, *optionalargs, **kwoptionalargs)

link((component,boxname),(component,boxname),**otherargs) -> new linkage

Creates a linkage from a named box on one component to a named box on another. See linkage class for meanings of other arguments. A linkage object is returned as a handle representing the linkage created.

The linkage is registered with this postoffice.

Throws Axon.AxonExceptions.BoxAlreadyLinkedToDestination if the source is already linked to somewhere else (Axon does not permit one-to-many).

unlink(self[, thecomponent][, thelinkage])

unlink([thecomponent][,thelinkage] -> destroys linkage(s).

Destroys the specified linkage, or linkages for the specified component.

Note, it only destroys linkages registered in this postoffice.


Destroys all linkages made with this postoffice.


Got a problem with the documentation? Something unclear that could be clearer? Want to help improve it? Constructive criticism is very welcome - especially if you can suggest a better rewording!

Please leave you feedback here in reply to the documentation thread in the Kamaelia blog.

-- Automatic documentation generator, 09 Dec 2009 at 04:00:25 UTC/GMT