Module RS - Reporting Station Base Classes

This module provides some simple implementations of the ReportingAPI.ReportingStation object type. These implementations are intended to be used as base classes in applications which launch KPs.

Classes

Three classes are provided. The most used is the base class of the other two, the NullRS. The other two each provide distinct facilities for servicing KPs. DebuggingRS simply prints out the traceback information received when a KP terminates abnormally, and MulticastRS implements an n-way dispatch of each ReportingStation method to other, possibly remote, ReportingStation instances.

NullRS ()

This class implements a simple ReportingStation which performs allocation of reporting IDs and provide empty implementations of the KPMigrationReceived() and KPTerminated() methods.

DebuggingRS ()

This class is a subclass of NullRS which prints information about the exception which caused a KP to terminate if it died abnormally.

MulticastRS (sbhOrRSlist)

The sbhOrRSlist parameter is a sequence of ILU binding handles or reporting station objects which should be added as targets. Each element of sbhOrRSlist is added using the add_station() method described below.

This class can be used to call multiple reporting stations rather than just one for any event which needs multiple recipients. Any number of reporting station objects may be set as targets using the server-side methods of these objects.

One important aspect to note about this class is that reporting stations registered as targets will be implicitly unregistered if there is any error in passing calls through. This protects the process running the MulticaseRS from having to deal with failures of the MulticastRS itself. When special handling is needed for reporting stations registered as targets, a callback may be registered for this purpose when the reporting station is registered.

NullRS Objects

No additional server-side methods are provided. Allocation of reporting IDs conforms to the description in Generation of IDs.

DebuggingRS Objects

The DebuggingRS class adds an additional server-side method and extends one standard method.

print_exception (id, reason, details, kprepr)

Print traceback information supplied by the KOS when a KP exits due to an exception. This method may be overridden to change the information printed or how the information is displayed.

KPTerminated (id, reason, details, kprepr)

Extension of NullRS implementation. If the KP died abnormally, failure information, including the traceback if available, is printed on the standard output using print_exception().

MulticastRS Objects

The MulticastRS overrides two methods of the base NullRS and provides a number of additional server-side methods to manage the set of target reporting stations.

Note that the AllocateID() method is not handled specially, and should not be used with MulticastRS objects.

add_station (sbhOrRS[, del_cb])

Add a reporting station to the set of targets handled by the MulticastRS instance. If sbhOrRS is a string, it must be the ILU binding handle for a reporting station object, otherwise it must be a ReportingAPI.ReportingStation instance.

If del_cb is given, it must be a callable object which will be called when the reporting station given by sbhOrRS is removed from the multicast set. This callback is made regardless of whether the station was removed due to an error in calling it or if the removal was explicitly requested via the remove_station() method.

If sbhOrRS is a string and the reporting station object it specifies cannot be located, information about the error is stored and can be retrieved using the get_error() method.

remove_station (sbh)

Remove the station with the ILU binding handle sbh from the multicast set, if present. If the station is present and was registered with a deletion callback, the callback will be called before this method returns.

get_station_count () -> integer

Return the number of target reporting stations registered in the multicast set.

get_error_count () -> integer

Return the number of errors encountered translating binding handles to reporting station objects.

get_error (index) -> (sbh, exc_type, exc_value)

Return information about a specific error encountered when registering a target. This method returns three values: the binding handle which was specified in the call to add_station(), the exception type, and the exception value. The exception type may be ilu.IluGeneralError or ilu.IluProtocolError; other exceptions are not caught by add_station(). The traceback is not retained since it is not very useful.

KPMigrationReceived (id, kpidTo, migratingTo)

Call the KPMigrationReceived() method of each target, removing the target for if an error is generated in performing the call.

KPTerminated(id, reason, details, kprepr)

Call the KPTerminated() method of each target, removing the target for if an error is generated in performing the call.

_apply(method, args) -> value

This method is only useful for derived classes. It calls the named method (a string naming a method) of each of the targets, with the argument list args (a tuple), removing the target for if an error is generated in performing the call. It returns the first return value that is not "false", if any.

Generation of IDs

The generation of IDs by the AllocateID() method of a ReportingStation object is required to maintain global uniqueness of the IDs used by KPs to report to their reporting stations and to support monitoring by the visuallizer. In the current implementation, a simple approach to generating unique IDs has been taken; the algorithm used will need to change in future versions of the KOE, but the interfaces should not need to change to accomodate this.

The current implementation forms unique IDs from the process ID of the NullRS (or subclass) instance, the prefix passed to the AllocateID() method, and a sequence number based on the prefix. Launching tools pass in a prefix based on the name of the file from which the KP was loaded, while cloning operations use the ID of the parent KP. This supports the generation of IDs of the form shown in Figure 1.

Figure 1. Form of unique IDs.

While process numbers are not globally unique, they are easy to access and not likely to match while any active KPs are running. As more hosts and clients are added to the environment, the chances for collision increase.