Learn more about Platform products at http://www.platform.com



EGO API


The EGO Application Programming Interface (API) is a collection of programming interfaces used by a client application to access EGO functionality. A client can be either registered or unregistered. Unregistered clients can perform queries for host and consumer information. Registered clients have access to additional functionality such as resource allocation and container execution.

Clients can interact with EGO through either the native C API or the Web Service interface.

EGO functionality

In order to take advantage of what the API has to offer, it is important to understand the core functions of the EGO kernel. These functions can be categorized as information, allocation, execution, and administration.

Information

Platform EGO aggregates information from all the hosts in the cluster providing a single point from which clients can request information about the state of any host. This includes the state of individual resources, the status of allocation requests, the consumer hierarchy including current resources assigned to each consumer, as well as activities that have been started in the distributed environment.

Allocation

A critical function of Platform EGO is to manage the allocation requests that come from different clients. Clients request and release CPU slots through the allocate and release interfaces identifying the number and type of resources they need based on various host attributes and the consumer they are being allocated on behalf of.

Based on the availability of resources and the amount of resources a consumer is entitled to, Platform EGO applies policies to determine how many resources to allocate to a given request. The client is notified asynchronously as the resources become available. In this case, CPU slots are identified by the physical host that they reside on and this host information is passed back to the client.

Execution

Once a client has obtained resources from Platform EGO, it will want to utilize those resources to perform work. Platform EGO provides a mechanism to allow clients to execute actions on the resources that have been allocated to them. In the typical case where compute hosts or CPU slots are the resources, execution action involves starting, stopping, and controlling execution activities.

Platform EGO instantiates OS-level processes on the hosts representing the container/activity and sets the execution context around the activity such as environment variables, working directories, and resource limits. Changes in the status of the activity on any host are reported asynchronously to the client enabling the client to handle these changes.

EGO API

This section describes the external interfaces available to a client application for invoking EGO services.

Client registration interface

Registration is required for clients to be able to request allocations and start activities. The client must also be registered in order to receive notifications (callbacks) for events related to the client's allocations, assigned resources, and activities.

Resource allocation interface

The EGO client uses the Resource Allocation Interface to request Platform EGO to allocate, change, release, replace or list resources. The client must register with Platform EGO using the client registration interface before being able to use any of the resource allocation interface operations.

Container management interface

The Container Management Interface supports the execution of activities on hosts managed by Platform EGO. An EGO client uses this interface to start its activities once it has the resources it needs through the resource allocation interface. This interface is also used to suspend, resume, and collect the status of a container.

Policy configuration interface

The Policy Configuration Interface allows for the setting of resource allocation policies in Platform EGO. The interface allows administrators to define consumers and place them in the consumer hierarchy. Policies are related to how resources should be divided between consumers at any given level of the hierarchy.

The policies at each consumer level specify parameters that control the division of resources among its children.

Resource monitoring interface

This interface supports operations to query information from the EGO master and cluster managed by the EGO master. The interface can also be used to collect information pertaining to a group of resources or pertaining to activities that were started by the EGO kernel.

Client notification interface

This interface supports a number of client notification operations such as informing the client to shut itself down or to informing the client that a resource has been added to the allocation. This interface is also used by the EGO kernel to notify the client of status changes in activities, named resources, or membership in resource groups.

Administration interface

This interface supports the control and management functions of EGO. This includes the vast number of operations that enable the cluster administrator to set up and manage entities such as resource host groups, users, and consumers.

API calls, callbacks, and notifications

API calls

All API calls are synchronous, meaning that a message sent by the client is expected to have a corresponding reply, i.e., the calling operation code has one and only one reply code. The client side blocks execution until the matching reply is received.

Synchronous call sequence: (callback is received while an API is blocking for reply)

    1. During an API call, the function waits for matching reply code.
    2. A message is received but API determines that it is not the reply to its call. The API places this message on a message queue internal to the client library.
    3. The function continues to wait until a matching reply code is received. The API pushes all other messages on the message queue.

EGO callbacks

Some calls to the C API, such as vem_alloc(), may result in asynchronous callbacks. At the time of registration, a client specifies callback functions that get executed when certain events occur in Platform EGO. The time when these functions get executed is not determined by when the functions are supplied so they are considered asynchronous. These callback messages can occur at any time, even when the client is waiting for a reply to another call.

Asynchronous callback sequence: (callback received outside of an API call)

    1. Client uses vem_select() to determine if there is a pendinging message from Platform EGO to be processed.
    2. Client uses vem_read() to retrieve the pending message.

EGO notifications

Instead of callbacks, the Web Service API uses notifications. Through the Web Service API, the client specifies a communication endpoint where Platform EGO sends a message when certain events happen.

API and Web Service interface reference documentation

Reference documentation for the C API and Web Service interface is available through the Eclipse Help menu.

C API

The C API documentation provides detailed descriptions of the API functions, structures, enumerations, and preprocessor directives. To access the C API documentation, select the reference documentation under EGO Developer Documentation in the Eclipse Help Contents pane.

Web Service interface

The Web Service reference documentation consists of WSDL and schema information. The WSDLs describe the Web Service interface (operations) and messages whereas the schemas describe the data types of the input/output arguments and their structure. To access the Web Service documentation, select the appropriate reference documentation under EGO Developer Documentation in the Eclipse Help Contents pane. The WSDL and schema documentation is also embedded in the individual WSDL and schema files.

[ Top ]


[ Platform Documentation ]


      Date Modified: July 12, 2006
Platform Computing: www.platform.com

Platform Support: support@platform.com
Platform Information Development: doc@platform.com

Copyright © 1994-2006 Platform Computing Corporation. All rights reserved.