Axon.Postoffice

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:

po.unlink(thelinkage=link3)

po.unlink(thecomponent=c3)

po.unlinkAll()

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)

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.