Kamaelia docs : Axon.CoordinatingAssistantTracker

Axon.CoordinatingAssistantTracker

Co-ordinating Assistant Tracker

class coordinatingassistanttracker

Accessing the Co-ordinating Assistant Tracker
Services
Tracking global statistics
Hierarchy of co-ordinating assistant trackers
Test documentation

The co-ordinating assistant tracker is designed to allow components to register services and statistics they wish to make public to the rest of the system. Components can also query the co-ordinating assistant tracker to create linkages to specific services, and for specific global statistics.

A co-ordinating assistant tracker is shared between several/all components
Components can register an inbox as a service with a name
Components can retrieve a service by its name

Accessing the Co-ordinating Assistant Tracker

Co-ordinating assistant trackers are designed to work in a singleton manner; accessible via a local or class interface (though this is not enforced).

The simplest way to obtain the global co-ordinating assistant tracker is via the getcat() class (static) method:

from Axon.CoordinatingAssistantTracker import coordinatingassistanttracker

theCAT = coordinatingassistanttracker.getcat()

The first time this method is called, the co-ordinating assistant tracker is created. Subsequent calls, wherever they are made from, return that same instance.

Services

Components can register a named inbox on a component as a named service. This provides a way for a component to provide a service for other components - an inbox that another component can look up and create a linkage to.

Registering a service is simple:

theComponent = MyComponentProvidingServiceOnItsInbox()
theComponent.activate()

theCAT = coordinatingassistanttracker.getcat()
theCAT.registerService("MY_SERVICE", theComponent, "inbox")

Another component can then retrieve the service:

theCAT = coordinatingassistanttracker.getcat()
(comp, inboxname) = theCAT.retrieveService("MY_SERVICE")

Because services are run by components - these by definition die and so also need to be de-registered:

theCAT = coordinatingassistanttracker.getcat()
theCAT.deRegisterService("MY_SERVICE")

Tracking global statistics

Microprocesses can also use the co-ordinating assistant tracker to log/retrieve statistics/information.

Use the trackValue() method to initially start tracking a value under a given name:

value = ...

theCAT = coordinatingassistanttracker.getcat()
theCAT.trackValue("MY_VALUE", value)

This can then be easily retrieved:

theCAT = coordinatingassistanttracker.getcat()
value= theCAT.retrieveValue("MY_VALUE")

Call the updateValue() method (not the trackValue() method) to update the value being tracked:

newvalue = ...

theCAT = coordinatingassistanttracker.getcat()
theCAT.updateValue("MY_VALUE", newvalue)

Hierarchy of co-ordinating assistant trackers

Although at initialisation a parent co-ordinating assistant tracker can be specified; this is not currently used.

Test documentation

Tests passed:

__init__ - Trying to set a anything other than a coordinated assistant tracker as the parent causes a BadParentTracker exception
__init__ - Called with no arguments should succeed.
__init__ - Called with a single argument results in it being the parent for the tracker
deRegisterService - allows a component to remove their service from being public
deRegisterService - deleting a non-existant service raises MultipleServiceDeletion exception
informationItemsLogged - returns the names of pieces of information logged with this tracker
registerService - adds the named component/inbox to the list of named registered services
registerService - adding a duplicate service fails, even with same arguments
registerService - adding a service but not to as a component fails- raises BadComponent assertion
registerService - adding a service but to a bad/nonexistant inbox fails - raises BadInbox assertion
retrieveService - Retrieving a tracked service should return the component/inbox pair we supplied under a specific name
retrieveService - Attempting to retrieve a non-tracked service results in KeyError exception being thrown
retrieveValue - Retrieving a tracked value should return the value we asked to be tracked
retrieveValue - attempting to retrieve a value we're not tracking should raise AccessToUndeclaredTrackedVariable
trackValue - Adding a value to be tracked twice raises NamespaceClash
trackValue - Adds the name/value pair to the set of info items logged
updateValue - Updating a value should result in the value stored being updated
updateValue - Updating a value not declared as tracked should raise AccessToUndeclaredTrackedVariable

Axon.CoordinatingAssistantTracker.coordinatingassistanttracker

class coordinatingassistanttracker(object)

coordinatingassistanttracker([parent]) -> new coordinatingassistanttracker object.

Co-ordinating assistant tracker object tracks values and (component,inboxname) services under names.

Keyword arguments:

parent -- Optional. None, or a parent coordinatingassistanttracker object.

Methods defined here

init(self[, parent])

deRegisterService(self, service)

Deregister a service that was previously registered.

Raises Axon.AxonExceptions.MultipleServiceDeletion if the service is not/ no longer registered.

informationItemsLogged(self)

Returns list of names values are being tracked under.

main(self)

registerService(self, service, thecomponent, inbox)

Keyword arguments:

service -- the name for the service
thecomponent -- the component offering the service
inbox -- name of the inbox on the component

Exceptions that may be raised:

retrieveService(self, name)

Retrieve the (component, inboxName) service with the specified name.

retrieveValue(self, name)

Retrieve the value tracked (recorded) under the specified name.

Trying to retrieve a value under a name that isn't yet being tracked results in an Axon.AxonExceptions.AccessToUndeclaredTrackedVariable exception being raised.

servicesRegistered(self)

Returns list of names of registered services

trackValue(self, name, value)

Track (record) the specified value under the specified name.

Once we start tracking a value, we have it's value forever (for now). Trying to track the same named value more than once causes an Axon.AxonExceptions.NamespaceClash exception. This is done to capture problems between interacting components

updateValue(self, name, value)

Update the value being tracked under the specified name with the new value provided.

Trying to update a value under a name that isn't yet being tracked results in an Axon.AxonExceptions.AccessToUndeclaredTrackedVariable exception being raised.

zap(self)

Feedback

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, 01 Feb 2010 at 04:00:28 UTC/GMT

Kamaelia is an open source project originated from and guided by BBC Research. For more information browse the site or get in contact.

This is an ongoing community based development site. As a result the contents of this page is the opinions of the contributors of the pages involved not the organisations involved. Specificially, this page may contain personal views which are not the views of the BBC. (the site is powered by a wiki engine)