The following IDL is based on the CORBA/OMG MAF specification. We used it to provide a platform independent interface to the task capsule framework described in this thesis. At the time this interface was designed the idea of a task capsule was not yet born. Therefore the term agent is found throughout this IDL specification.
module CERNMAF {
// Forward declaration
interface DataFaucet;
//
// AgentSystemType was ment to be a short integer,
// but our notation requires more...
// AgentSystemType = site.subsystem.node = 999.99.999 (2^32 = long)
//
typedef sequence<octet> OctetString;
typedef unsigned long AgentSystemType;
typedef unsigned short PartitionNumberT;
typedef double AuthorityT;
typedef unsigned long IdentityT;
typedef unsigned short LanguageID;
//
// NodeT
// Is dependent on the network type of course. We make it as
// generic as possible. MAF calls ``it Location'', we speak of ``nodes''.
//
typedef enum NetEnum {eInternet, eMyrinet, eFibreChannel, eVME, ePCI} NetT;
struct NodeT
{
NetT network; // Internet, FibreChannel, Myrinet, DLPI access
string name; // node name in the format of the net, e.g. 192.160.231.33
};
//
// NameT
// hold the name of an agent. The name
// indicates the agents creation place
//
struct NameT {
AuthorityT authority; // e.g. IP Address
IdentityT identity; // a running ID, increased when registered.
AgentSystemType agentSystem; // where the agent was defined, Internet
};
typedef sequence<NameT> NameList;
//
// Non MAF standard
// For clients who want to know more about the agent, e.g.
// what kind of task it executes.
//
struct ExtendedNameT {
NameT agentName;
string agentDescription;
};
typedef sequence<ExtendedNameT> ExtendedNameList;
//
// PropertyT
// holds the properties an agent can have. in the orginial
// OMG-MAF specification this structure holds two entries,
// a property´s name and a value. Then this strcture is used
// for entries in a property list.
// In the CMS experiment, we choose a fixed property structure.
// It can be extended, by extending the structure. Interpreting
// a list of properties at each site is too costly.
//
struct TimeValT {
short year;
short month;
short day;
short hour;
short minute;
short second;
short msec;
short usec;
};
//
// type is absolute date or the current time plus an interval.
// value is the time value
//
typedef enum TimeSpecEnum {absolute, relative} TimeSpecT;
struct TimeT {
TimeSpecT type;
TimeValT value;
};
//
// Trigger gives the start time of the execution, the deadline
// that has to be met and how long has to be waited before the
// next exeuction. If that is zero, the agent is executed only once.
//
struct TriggerT {
TimeT start;
TimeT deadline;
TimeT interval;
};
//
// The execution mode of the agent. Determines if the agent
// is a user task or a system policy object.
//
typedef enum ModeEnum {
Exclusive,
Privileged,
NonPrivileged
} ModeT;
//
// TBD.
//
typedef enum PriorityEnum {
NotYetDefined
} PriorityT;
//
// The type of the agent. Either it is an ordinary function that
// is called, or a thread or an external process.
//
typedef enum processingEnum {
Synchronous,
AsyncThread,
AsyncProcess
} ProcessingT;
struct AgentPropertyT {
//
// Mode:
// Exclusive - The queue is halted, this agent is the only one
// that is processed in the system. All internal system
// status is made accessible to this agent. No other agents
// are accepted at the service socket.
// Privileged - Internal system status is visible, but scheduling of other
// agents is allowed.
// NonPrivileged - Ordinary agent execution
//
ModeT mode;
//
// Priority:
// TBD.
//
PriorityT priority;
//
// ProcessingType:
// Synchronous - an ordinary function call is performed
// AsyncThread - The Agent is started in a thread.
// AsyncProcess - The Agent is started in a process
//
ProcessingT processingType;
TriggerT trigger; // Time information for agent execution
};
//
// AgentStatusT:
// This structure may be filled on any site where the agent is
// executed. It is stored there and fetched by a completion agent
// or immediately taken when the synchronous execution is finished.
// A list of such structs is the returned to the originator.
//
// There will also be a list of return values, but these are
// defined with the agent directly.
//
typedef enum ProcessingStatusEnum {
Ready,
Running,
Suspended,
Finished,
Failed,
Aborted,
Undefined,
CORBAFailed
} ProcessingStatusT;
struct AgentStatusT
{
//
// Status:
// Ready - Agent is waiting for execution
// Running - Agent is running
// Suspended - Agent was suspended by the Agent System on request
// Finished - Agent finished correctly and in time
// Failed - Missed deadline or failed otherwise, check the errorCode!
// Aborted - Agent was canceled by the Agent System
//
ProcessingStatusT processingStatus;
NodeT node; // The site at which the entry was done;
boolean visited; // Indicates if the agent already visited that site.
short errorCode; // Detailed information about the agents completion
short logCount; // Log entries have been made (they can be retrieved).
};
//
// A list that contains the status information of an agent at every node
// The list is already created, before the agent leaves from its home
// base. Therefore it also represents the itinerary of the agent.
// The node entries start with the home base name and end with it.
//
typedef sequence<AgentStatusT> AgentStatusList;
//
// LanguageID gives the programming language of the agent.
// agentType is something like: cern.cms.filterFarm.monitor
// agentDescription is the classname of the agent.
// Version is the code version
// OMG proposes a list of properties, we supply a single structure
//
struct AgentProfileT
{
LanguageID languageID;
AgentSystemType agentType;
string agentDescription;
short majorVersion;
short minorVersion;
AgentPropertyT properties;
};
typedef sequence<NodeT> NodeList; // A list of network nodes
struct CoreStructT {
NodeList neighbours; // determines the network topology
TimeT startup; // AgentCores startup time
short errorCount; // number of errors since startup
short logCount; // Log entries have been made (they can be retrieved).
short agents; // Number of local agents
boolean open; // Accepts agents or not (exclusive mode!)
}; // CoreT;
typedef enum EndianEnum {Big, Little} EndianT;
struct CPUStructT {
short cpuID; // 1-586-2 -> Intel-Pentium-II
short nCPUs; // Number of CPUs
string OS; // Operating System name and version, e.g: VxWorks40
EndianT endian;
}; // CPUT;
// Store System properties
//
typedef sequence<any> SystemPropertyList;
struct AgentSystemInfo
{
NameT systemName; // e.g. FilterFarm
AgentSystemType systemType; // e.g. FilterFarm in number code
string systemDescription; // e.g. CMS-FU-AgentCore, CMS-EVM-AC
short majorVersion;
short minorVersion;
SystemPropertyList properties;
};
typedef sequence<string> Strings;
struct ArgumentsT {
short argc;
Strings argv;
};
typedef enum EnvTagEnum {
eEntryPull,
eEntryPush,
eEntryDelivered,
eEntryNone} EnvTag;
struct EnvironmentEntry {
any data;
TimeValT timestamp;
EnvTag tag;
};
//
// Exceptions that can be raised when requesting a
// service from the agent execution framework.
//
exception ClassUnknown {};
exception ArgumentInvalid {};
exception AgentNotFound {};
exception EntryNotFound {};
exception InformationNotAccessible {};
exception RejectExclusive {};
exception OperationFailed {};
exception TerminationFailed {};
interface AgentSystem {
//
// Create an agent at a remote site. The site list the agent
// has to visit is given in the itinerary parameter. A non-travelling
// implementation just has to replace this by nodeT and the server
// has to take care of calling the operation several times.
//
// agentName - the identifier.
// The Authority that is passed is the type of the agent.
// The AgentSystem is that, where the agent is created,
// so if it is created from a data faucet, it is 0 or
// we find a clever way to identify data faucets!!!
// e.g. institute-number or so.
// The identifier is a local counter that is increased
// on every create.
// agentProfile - attributes necessary for execution
// arguments - arguments for the agent constructor
// itinerary - a list of places to be visited (first = last = originator)
// codeBase - a string that identifies the agent code to be loaded
// exception ClassUnknown - raised if the agent code base cannot be found.
// exception ArguemtnInvalid - raised if the profile cannot be accepted.
// create_agent is done on behalf of a clients request.
//@@ deviation from MAF: in NameT -> inout NameT
// Data faucet creates an id.
//
short create_agent (
inout NameT agentName,
in AgentProfileT agentProfile,
in ArgumentsT arguments,
in AgentStatusList itinerary,
in string codeBase
)
raises (ClassUnknown, ArgumentInvalid, RejectExclusive);
//
// Same as above, nut this operation is called from an agent
// system, when it forwards the agent to another place.
// The agentName is not a new one, it is just forwarded,
// the same happens to the other parameters.
//
short receive_agent (
in NameT agentName,
in AgentProfileT agentProfile,
in ArgumentsT arguments,
in AgentStatusList itinerary,
in string codeBase
)
raises (ClassUnknown, ArgumentInvalid, RejectExclusive);
//
// get_agent_environment, non standard
// searches the agent n all nodes and initiates a callback
// to the data faucet from all nodes, containing pending
// requests with the tag "Pull".
//
short get_agent_environment (in AgentStatusList itinerary,
in NameT agentName, in DataFaucet callback)
raises (InformationNotAccessible);
//
// set_agent_environment, non standard
// For writing untagged data into the environment of an agent
// on ALL nodes. the timestamp is that of the data faucet.
//
short set_agent_environment (in AgentStatusList itinerary,
in NameT agentName,
in EnvironmentEntry envData);
//
// get_agent_status
// is here for the case, that we want to query single agents on a place.
// Normally the agent status is retrieved by a status agent... still, for
// smaller systems this could be useful.
// The place is not specified in the call, as this is done by the main
// application that calls that operation.
// exception AgentNotFound - the specified agent is not on this host.
// exception Information...- the Information cannot be given to you.
//
AgentStatusT get_agent_status (in NameT agent_name)
raises (AgentNotFound, InformationNotAccessible);
//
// Not MAF compliant: lookup agent really is in
// MAFRepository once implemented and has other arguments
// Locations lookup_agent (in NameT agentName, in AgentProfileT
agentProfile)
//
NodeList lookup_agent (in NameT agentName)
raises (AgentNotFound);
//
// get_agent_system_info()
// Same as above, but now for the actual processing entities.
//
AgentSystemInfo get_agent_system_info()
raises (InformationNotAccessible);
//
// list_all_agents()
// List agents that are available on this node (ready, running, ...)
// Not MAF compliant: added AgentDescription.
//
ExtendedNameList list_all_agents()
raises (InformationNotAccessible);
//
// Not MAF compliant: register_callback
//
void register_callback (in AgentStatusList itinerary, in DataFaucet callback);
//
// dump
// Tells the agent core to call dump on the specified agents,
// gather the results are provide it to the caller.
// Dump must be implemented by the agents. There is not specification
// or rule, what the data that is dumped consists of.
// DataFaucet also has a dump method. It accepts type any and
// routes the any type to the UI that is associated with this
// agent.
//
short dump (in AgentStatusList itinerary,
in NameT agent_name, in DataFaucet callback);
void stuff (in AgentStatusList itinerary, in NameT agent_name, in any data);
void terminate_agent (in AgentStatusList itinerary, in NameT agent_name);
void suspend_agent (in AgentStatusList itinerary, in NameT agent_name);
void resume_agent (in AgentStatusList itinerary, in NameT agent_name);
void terminate_agent_system() raises (TerminationFailed);
};
interface DataFaucet
{
// The callback for the agents when they want to
// publish data from their environment or when data
// from their environment is collected.
//
short PublishEnvironment (
in NodeT node,
in NameT agent,
in EnvironmentEntry envData);
// The callback for the agent dump method
short dump (in NodeT node, in NameT agent, in any data);
// An Error message callback
// There should be a callback for information, etc. too.
void DeliverStatus (in AgentStatusList itinerary);
void test();
};
//
// MAFRepository
// is used to keep track of all agents and nodes in the
// system. There may be many repositories, e.g. one in the
// U.S., one at CERN. Just before you initiate an agent
// transport, you can query your nearest repository and
// then pass a list of nodes and the agent.
//
interface MAFRepository
{
//
// List all nodes in a given domain
//
NodeList list_all_places(in AgentSystemType domain);
//
// Register a node to be in a subsystem of CMS.
// e.g. Node 123 in domain FilterFarm
// A domain is not one identifier. It can well be structured, like:
// /cern/cms/filterFarm = site.experiment.subsystem = 25.98.77 =
259877
//
void register_place (in NodeT node_name, in AgentSystemType domain);
void unregister_place (in NodeT node_name)
raises (EntryNotFound);
// The operations for register AgentSystem and
// unregister AgentSystem are not there yet.
};
};