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.

(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.

Exceptions:

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?)

Exceptions:

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.

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.)

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.

Exceptions:

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.

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.

Exceptions:

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.

Exceptions:

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.

Exceptions:

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.

Exceptions:

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".

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.

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.)

Exceptions:

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.

Exceptions:

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.

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.

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.

Exceptions:

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.