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.
- 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.
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.
- pickle.PicklingError
- An error occurred saving the state of the current
KP.
(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.
Exceptions:
- 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.
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".
- 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.
Exceptions:
- 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.)
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.
Exceptions:
- 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.
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.
Exceptions:
- KOSKernel.NotFound
- An internal KSS error occured
- TypeError
- The cvar argument was not a condition
variable instance.