Interface Specification for KOSKernel

Overview

The KOSKernel ISL file specifies a set of interfaces to objects that facilitate syncronization of various KOS system state information. These interfaces provide some glue between condition variables, KOS process entries, KOS plugin entries, and KP entry objects.

Note: this file uses unnecessarily arcane terminology developed early on in the design of the KOE. Terms such as "connector" are no longer used outside the project. When you see the word "connector" in this document and the corresponding ISL file, you can loosely read "service".

Type Definitions

The following non-OBJECT types are defined by this interface:

String

An alias for ilu.CString

StringSequence

An alias for SEQUENCE OF String

CID

An alias for String, used as an ILU String Binding Handle (SBH) representing a connector object.

CnType

An alias for String, indicates a connector type name.

ConditionID

An alias for Integer.

Exceptions

The following exceptions are defined by this interface:

NotFound

Raised when the requested object is not found.

NotPermitted

Raised when there is insufficient authority for requested operation.

Condition Objects

An object to put in the namespace, so that conditions can be shared. A program that wants to register a trigger gets a Condition out of the namespace and passes it to the Supervisor. This object has the following methods:

GetID () : ConditionID

Return the identifier of the condition variable represented by this object.

ProcessLink

The ProcessLink allows the KOS kernel to communicate with subprocesses. It is the dual of the ProcessEntry (see below). The KOS uses this interface to communication with the subprocess, which holds the true object. This object has the following methods:

ASYNCRONOUS Signal (var : ConditionID)

Queue and process a signal event on the condition variable specified by the identifier.

ASYNCRONOUS Broadcast (var : ConditionID)

Queue and process a broadcast even on the condition variable specified by the identifier.

ProcessEntry

The ProcessEntry links a subprocess with the KOS kernel. The ProcessEntry true server is part of the kernel process, and the subprocess uses this object's interface to communicate with the KOS. This object has the following methods:

EstablishProcessLink (link : ConditionID)

Establish a link for the KOS to make calls to the subprocess. This is called as a side-effect of the KPEntry.Hello() method (see below), to establish a (reverse) connection from the kernel to the supervisor.

RegisterConnector (instance : CID, type : CnType, name : String)

Create an entry for a connector instance in the KOS kernel.

UnregisterConnector (instance : CID)

Remove an entry for the connector instance. Raises NotFound if no instance for the provided CID is found. Raises NotPermitted if the caller does not own the connector.

CreateCondition () : ConditionID

Creates a new condition variable.

Broadcast (var : ConditionID)

Notify all triggers waiting on the condition variable var. Raises NotFound if no condition variable for var is found.

Signal (var : ConditionID)

Notify exactly one trigger waiting on the condition variable var. If more than one trigger is waiting on var, then an arbitrary trigger is chosen. Raises NotFound if no condition variable for var is found.

RegisterTrigger (var : ConditionID)

Register a trigger on the condition variable var for the process associated with this ProcessEntry object. Raises NotFound if no condition variable for var is found.

UnregisterTrigger (var : ConnectionID)

Unregister the trigger associated with condition variable var corresponding for the process associated with this ProcessEntry object. Raises NotFound if no condition variable for var is found.

PluginEntry Objects

The kernel's communication link with a plugin subprocess. This object defines no new methods from its supertype, ProcessEntry.

KPEntry Objects

The kernel's communication link with a KP subprocess. This object defines the following methods in addition to those defined by its supertype, ProcessEntry:

Hello (link : ProcessLink, OUT ks-name : String, OUT kpid : KOS.KPID, OUT kprepr : KPRepr.Representation, OUT visualizer : ReportingAPI.Visualizer, OUT nsd : Namespace.Descriptor)

Initial handshake between the KP's supervisor and the kernel. link is the ProcessLink object representing the Supervisor.

There is no explicit return value for this method, but information is returned by filling the output parameters as a side effect of this call:

• kos-name is the kernel's name
• kpid is the KP's unique identifier, unique to this kernel.
• kprepr is the KP's Representation object
• visualizer is the Visualizer object associated with the kernel.
• nsd is the descriptor of a Context object representing the namespace of the KP which lives in kernel.

Goodbye (new-kpid : KOS.KPID, new-kos-name : String)

Called by the Supervisor when this KP has left the current KOS via process migration. new-kpid is the migrated KP's new identifier, unique to the destination KOS. new-kos-name is the name of the destination KOS.

Terminated (reason : String, details : String)

Called by the Supervisor when this KP has terminated. reason will be the empty string if the KP terminated normally, or a string describing the exception that occurred if the KP exited due to an error. details will be the exit status of the KP as a string if it exited normally, or the string value of the exception if it exited due to an error.