KOS Bastion Methods

The KOS bastion object is passed to KPs as the argument to the __main__() method. Plugins also receive a KOS bastion object, via pluginlib.register(), but this object doesn't have the first seven methods.

All methods in this interface may raise the ILU exceptions IluGeneralError, IluProtocolError, and IluUnimplementedMethodError. To avoid repetition, these are not listed explicitly in the list of exceptions for each method.

KP-specific KOS Bastion Methods

(Implementation note: these methods are defined in the Supervisor module.)

checkpoint ()

Save the state of the KP in the KP representation maintained by the KSS kernel. When a KP finishes executing, its program state is normally not saved, and the program state in the KP representation, if any, represents the program state at the time the KP last migrated or was created as a clone. The checkpoint() saves the current state of the KP so that it will be available for inspection when the KP finishes.

pickle.PicklingError: An error occurred saving the state of the current KP. (See the Python documentation for the pickle module for the restrictions that apply to instance variables so that they can be pickled, and how to customize the pickling and unpickling process.)

clone ([destination])

Create a duplicate of the current KP and submit it to the KSS specified by the string destination. The default destination is the current KSS. See the section on managing clones in the KP interface documentation.

The new KP is identical to the current KP except that it receives a new reporting ID before it is submitted to its destination. The new reporting ID is assigned by the KP's reporting station, which can refuse to allow a clone call. (XXX Wouldn't it be nice if clone() returned the reporting ID?)

KOS.CommunicationError: Communication with the KP's reporting station or the destination KSS failed.
KOS.AuthorizationError: The reporting station refused to issue a reporting ID or the destination KSS did not accept the new KP.
KOS.EncodingError: Submission of the new KP failed because of an internal error.
KOS.MetadataError: Submission of the new KP failed because of an internal error.
KOS.ResourceError: Submission of the new KP failed because an internal KSS resource was unavailable at the destination.
pickle.PicklingError: An error occurred saving the current state of the KP. (See above for details.)

get_kos_name () -> string

Return the name of the current KSS.

get_kphandle () -> string

Return a unique identifier for the current KP process -- the KP handle. This handle is unique for the current instance of the KP; if a KP migrates or clones, the new KP will have a different handle. (Implementation note: the returned string is currently of the form "kosname-kpid" where kosname is the name of the current KSS and kpid is the numeric ``KP ID'' assigned to the KP by this KSS.

get_namespace () -> nstools.Context instance

Return a namespace context for the current KP. This context is created by the KSS when a new KP arrives. Initially, it has two bindings: 'kos' is bound to the KSS's namespace and 'world' is bound to the worldroot namespace. (Alternatively, KPs can use nstools.WorldOpen() for their namespace needs.)

get_suitcase () -> Suitcase.SuitcaseFilesystem instance

Return a reference to the KP's suitcase filesystem. See the documentation for the Suitcase module, and the section on the suitcase in the KP interface documentation.

migrate (destination)

Stop execution of the current KP, save its state, and submit it to the KSS named destination. The KP will resume execution in its __main__() method at the new KSS. This call does not return when successful.

XXX cross reference pickle/state discussion.

KOS.CommunicationError: Communication with the destination KSS failed.
KOS.AuthorizationError: The destination KSS refused to accept the KP submission.
KOS.EncodingError: Submission of the KP failed because of an internal error.
KOS.MetadataError: Submission of the KP failed because of an internal error.
KOS.ResourceError: Submission of the KP failed because an internal KSS resource was unavailable at the destination.
pickle.PicklingError: An error occurred saving the state of the current KP.

Generic KOS Bastion Methods

(Implementation note: these methods are defined in the CnBroker module.)

all_exceptions (module) -> list of exception objects

Return a list of all the exceptions defined for the connector interface module. See the section on catching exceptions in the KP interface documentation.

ImportError: The named interface module does not exist.

bind _service (name, instance, type) -> nstools.Descriptor instance

Register a new connector in the KSS's namespace with the name name. The object instance must implement the connector type type. Before other processes can use the connector, the KP must call the KOS bastion method run() (see below). See the section on providing a service to other KPs in the KP interface documentation.

Namespace.BindError: A connector with the same name already exists.

broadcast (cvar)

Send a broadcast to the condition variable cvar. This is a variant of signal() that causes a callback in all KPs that have registered a callback for cvar. See the section on using trigger variables in the KP interface documentation.

KOSKernel.ConditionNotFound: The cvar is invalid.

create_condition (name) -> condition variable

Create a new condition variable named name. See the section on using trigger variables in the KP interface documentation.

Namespace.BindError: A condition variable named name already exists

exception (name) -> exception object

Return the exception named name, which must be a string of the form "module.exception". See the section on catching exceptions in the KP interface documentation.

ImportError: The named interface module does not exist.
ValueError: The exception does not exist in the named interface module.

list_services (type) -> list of strings

Return a list containing the names of all services of type type, which must be a string of the form "module.class".

list_service_types () -> list of strings

Return a list containing all service types for which one or more services have ever been registered with the current KOS kernel incarnation. The service types have the form "module.class".

lookup_service (name, type) -> nstools.Descriptor instance

Return a descriptor for the service named name. The service type must be type (i.e. the operation fails if the named service exists but has a different type). See the documentation for the nstools module for information on descriptors.

Note: in order to interact with the service object referenced by the descriptor, use the descriptor's Open() method, which returns an ILU surrogate for the service object.

nstools.BadPathError: The specified connector does not exist

register_trigger (cvar, callback)

Arrange that the function callback will be called the next time the condition variable cvar is signalled. Before the callback is activated, the KP must call the KOS bastion method run() (see below). The callback function will be called without any arguments. See the section on using trigger variables in the KP interface documentation.

Note: the callback will be called at most once; in order to have a permanent callback, the callback function must re-register itself by calling register_trigger() again. (XXX And this causes a race condition in case the condition variable is signalled again before the callback runs. This is one reason why triggers are not easy to use.)

KOSKernel.NotFound: An internal KSS error occured
TypeError: The cvar argument was not a condition variable instance.

run ()

Start the ILU mainloop and service requests to connectors. This call will not return until stop() is called. Only one call is necessary (until stop() is called). See the section on providing a service to other KPs in the KP interface documentation.

This call is also required in order to activate callbacks for condition variables.

RuntimeError: run() has already been called and cannot be called again until after stop() has been called.

signal (cvar)

Send a signal to the condition variable cvar. This causes a callback in one of the KPs that have registered a callback for cvar. If more than one KP has registered a callback for cvar, one is chosen at random. To signal all registered KPs, use broadcast(). See the section on using trigger variables in the KP interface documentation.

KOSKernel.ConditionNotFound: The cvar is invalid.

stop ()

Stop the ILU mainloop. See the section on providing a service to other KPs in the KP interface documentation.

Note: if the ILU mainloop is currently not active (i.e. if stop() is called before run()), the next call to run() will return immediately. This seems strange at first but is necessary in order to prevent a race condition that can occur if the callback that calls stop() happens to be invoked from the temporary ILU mainloop that is started whenever ILU waits for the response to an outgoing call.

stop_all_services ()

Unbind all services bound by the current KP or plugin. See the section on providing a service to other KPs in the KP interface documentation.

Note: despite its name, this does not stop the ILU mainloop.

stop_all_triggers ()

Unregister all callbacks on condition variables registered by the current KP or plugin. See the section on using trigger variables in the KP interface documentation.

Note: despite its name, this does not stop the ILU mainloop.

unbind_service (descriptor)

Remove a connector. The argument must be the descriptor returned by the bind_service() call that created the connector. See the section on providing a service to other KPs in the KP interface documentation.

ValueError: The descriptor does not reference a connector created by this KP.

unregister_trigger (cvar, callback)

Remove the arrangement for function callback to be called when condition variable cvar is signalled. If callback is not one of the registered callbacks for cvar, the call is ignored (i.e. no exception is raised). See the section on using trigger variables in the KP interface documentation.

KOSKernel.NotFound: An internal KSS error occured
TypeError: The cvar argument was not a condition variable instance.