Visit Platform at http://www.platform.com

vem.api.h File Reference


Data Structures

struct  vem_message
 VEM message. More...
struct  vem_host
 VEM host slot. More...
struct  vem_hostattr
 VEM host attribute. More...
struct  vem_allocreply
 VEM allocation reply message content. More...
struct  vem_reclaim
 VEM allocation reclaim. More...
struct  vem_allocreclaim
 VEM allocation reclaim message content. More...
struct  vem_allocreq
 VEM allocation request. More...
struct  vem_allocfreereq
 VEM allocation free request. More...
struct  vem_clientcallback
 VEM client callback. More...
struct  vem_registerreq
 VEM register request. More...
struct  vem_openreq
 VEM open request. More...
struct  vem_libparams
 VEM openbyname request. More...
struct  vem_container_spec
 Container specification used when invoking vem_startcontainer(). More...
struct  vem_startcontainerreq
 Start workload container request. More...
struct  vem_signalcontainerreq
 Signal workload container request. More...
struct  vem_container
 Workload container information. More...
struct  vem_container_info_reply
 Workload container information reply. More...
struct  vem_allocation
 Allocation information. More...
struct  vem_allocation_info_reply
 Allocation information reply. More...
struct  vem_reclaim_info_reply
 Reclaim information reply. More...
struct  vem_allocinforeq
 Query allocation information request. More...
struct  vem_clientinfo
 VEM client info. More...
struct  vem_reallocreq
 VEM resource reallocation request. More...
struct  vem_releasereq
 VEM resource release/replace request. More...
struct  vem_hostinfo
 VEM host information. More...
struct  vem_hostinforeq
 VEM host information request. More...
struct  vem_hostsummary
 VEM host summary. More...
struct  vem_masterlist
 VEM Master list. More...
struct  vem_hosttypes
 VEM active host types. More...

Defines

#define VEM_REGISTER_TTL   (0x2)
 Time to live flag.
#define VEM_REGISTER_FORCE   (0x4)
 Force Register.
#define DEF_CONTAINER_CONTROL_WAITPERIOD   60 * 2
#define VEM_REALLOC_DELTA   (0x1)
#define VEM_RELEASE_AUTOADJ   (0x1)
#define VEM_RELEASE_BLOCKED   (0x2)
#define VEM_RELEASE_MODIFY   (0x4)
#define VEM_HOST_OK   0x0
#define VEM_HOST_LIM_UNAVAIL   0x01
#define VEM_HOST_PEM_UNAVAIL   0x02
#define VEM_HOST_PEM_FATAL   0x04
#define VEM_HOST_UNLICENSE   0x08
#define VEM_HOST_LOCK_ADMIN   0x10
#define VEM_HOST_LOCK_WIND   0x20
#define VEM_HOST_LOCK_MASTER   0x40
#define VEM_HOST_LOCK_HPC   0x80
#define VEM_HOST_BUSY   0x100
#define VEM_HOST_CLOSE_ADMIN   0x200
#define VEM_HOST_REMOVED   0x400
#define VEM_HOST_CLOSE_RECLAIM_ADMIN   0x800
#define VEM_HOST_CLOSE_RECLAIM_THRESHOLD   0x1000

Typedefs

typedef enum vem_message_code vem_message_code_t
 VEM Message code.
typedef vem_message vem_message_t
 VEM message.
typedef vem_host vem_host_t
 VEM host slot.
typedef vem_hostattr vem_hostattr_t
 VEM host attribute.
typedef vem_allocreply vem_allocreply_t
 VEM allocation reply message content.
typedef vem_reclaim vem_reclaim_t
 VEM allocation reclaim.
typedef vem_allocreclaim vem_allocreclaim_t
 VEM allocation reclaim message content.
typedef vem_allocreq vem_allocreq_t
 VEM allocation request.
typedef vem_allocfreereq vem_allocfreereq_t
 VEM allocation free request.
typedef vem_clientcallback vem_clientcallback_t
 VEM client callback.
typedef vem_registerreq vem_registerreq_t
 VEM register request.
typedef vem_openreq vem_openreq_t
 VEM open request.
typedef vem_handle vem_handle_t
 VEM handle.
typedef vem_container_spec vem_container_spec_t
 Container specification used when invoking vem_startcontainer().
typedef vem_startcontainerreq vem_startcontainerreq_t
 Start workload container request.
typedef vem_signalcontainerreq vem_signalcontainerreq_t
 Signal workload container request.
typedef vem_container vem_container_t
 Workload container information.
typedef vem_container_info_reply vem_container_info_reply_t
 Workload container information reply.
typedef vem_allocation vem_allocation_t
 Allocation information.
typedef vem_allocation_info_reply vem_allocation_info_reply_t
 Allocation information reply.
typedef vem_reclaim_info_reply vem_reclaim_info_reply_t
 Reclaim information reply.
typedef vem_allocinforeq vem_allocinforeq_t
 Query allocation information request.
typedef vem_clientinfo vem_clientinfo_t
 VEM client info.
typedef vem_reallocreq vem_reallocreq_t
 VEM resource reallocation request.
typedef vem_releasereq vem_releasereq_t
 VEM resource release/replace request.
typedef vem_hostinfo vem_hostinfo_t
 VEM host information.
typedef vem_hostinforeq vem_hostinforeq_t
 VEM host information request.
typedef vem_hostsummary vem_hostsummary_t
 VEM host summary.
typedef vem_masterlist vem_masterlist_t
 VEM Master list.
typedef vem_hosttypes vem_hosttypes_t
 VEM active host types.

Enumerations

enum  vem_message_code {
  UNKNOWN_MSG, RESOURCE_ADD, RESOURCE_RECLAIM, CONTAINER_STATE_CHG,
  HOST_STATE_CHANGE
}
 VEM Message code. More...
enum  
 VEM Transport Security code. More...
enum  vem_container_exit_reason_t {
  ER_NULL = 0, ER_SETUP_NO_MEM, ER_SETUP_FORK, ER_SETUP_PGID,
  ER_SETUP_ENV, ER_SETUP_LIMIT, ER_SETUP_NO_USER, ER_SETUP_PATH,
  ER_SIG_KILL, ER_UNKNOWN, ER_PEM_UNREACH, ER_PEM_SYN,
  ER_NOSUCH_HOST, ER_NOSUCH_ALLOC, ER_BAD_ALLOC_HOST, ER_NOSUCH_CLIENT,
  ER_START, ER_NOSUCH_CMD, ER_CMD_EXEC, ER_JOBCTL_KILL,
  ER_JOBCTL_FAILED , LAST_EXIT_REASON
}
 Workload container exit reasons. More...
enum  vem_debug_code {
  DEBUG_VEMKD_ON, DEBUG_VEMKD_OFF, DEBUG_PEM_ON, DEBUG_PEM_OFF,
  DEBUG_LIM_ON, DEBUG_LIM_OFF
}

Functions

LIBVEM_API vem_handle_tvem_openbyname (int, struct vem_libparams *)
 Open commuication handle to VEM.
LIBVEM_API int vem_containerinfo (struct vem_handle *, vem_container_info_reply_t *)
 Query container information for a consumer.
LIBVEM_API int vem_get_avail_resources_for_consumer (vem_handle_t *, const char *, const char *, vem_avail_resources_t *)
LIBVEM_API int vem_setpolicyparams (vem_handle_t *, vem_policy_params_t *)
LIBVEM_API void * vem_malloc (size_t)
 wrapper on malloc. Routine is used when passing memory to vem api where it is expected to free.
LIBVEM_API void vem_free_string (char **)
 free a string
LIBVEM_API void vem_clear_masterlist (vem_masterlist_t *)
 Clear master list.
LIBVEM_API void vem_clear_hosttypes (vem_hosttypes_t *)
 Clear host types.
LIBVEM_API void vem_clear_hostsummary (vem_hostsummary_t *)
 Clear host summary.
LIBVEM_API void vem_free_hostinfo (vem_hostinfo_t *, int, char **)
 Free host information.
LIBVEM_API void vem_free_allocreply (vem_allocreply_t *)
 Free allocation reply message.
LIBVEM_API void vem_free_allocreclaim (vem_allocreclaim_t *)
 Free allocation reclaim message.
LIBVEM_API void vem_free_containerstatechg (vem_containerstatechg_t *)
 Free container state change message.
LIBVEM_API void vem_free_hoststatechange (vem_hoststatechange_t *)
 Free host state change message.
LIBVEM_API void vem_free_message (vem_message_t *)
 Free message.
LIBVEM_API void vem_clear_message (vem_message_t *)
 Clear message.
LIBVEM_API void vem_init_containerSpec (vem_container_spec_t *)
 Initialize container specification.
LIBVEM_API vem_container_spec_tvem_create_containerSpec (void)
 Create initialized container specification.
LIBVEM_API void vem_free_containerSpec (vem_container_spec_t *)
 Free container specification.
LIBVEM_API void vem_free_containerId (vem_container_id_t)
 Free container id.
LIBVEM_API void vem_clear_clientinfo (vem_clientinfo_t *)
 Clear client info.
LIBVEM_API void vem_free_clientinfo_array (vem_clientinfo_t **, int)
 Free client info array.
LIBVEM_API void vem_clear_controlhostreq (vem_controlhostreq_t *)
 Clear control host request.
LIBVEM_API void vem_free_uname (vem_name_t *)
 Free uname structure.
LIBVEM_API void vem_free_role_array (vem_role_t **, int)
 Free role structure array.
LIBVEM_API void vem_free_user_array (char ***, int)
 Free user structure array.
LIBVEM_API vem_allocreply_tvem_dup_allocreply (vem_allocreply_t *)
 Duplicate allocation reply message.
LIBVEM_API vem_allocreclaim_tvem_dup_allocreclaim (vem_allocreclaim_t *)
 Duplicate allocation reclaim message.
LIBVEM_API vem_containerstatechg_t * vem_dup_containerstatechg (vem_containerstatechg_t *)
 Duplicate container state change message.
LIBVEM_API vem_hoststatechange_t * vem_dup_hoststatechange (vem_hoststatechange_t *)
 Duplicate host state change message.
LIBVEM_API void vem_clear_allocation (vem_allocation_t *)
 Clear allocation structure.
LIBVEM_API void vem_clear_allocationInfoReply (vem_allocation_info_reply_t *)
 Clear vem_allocation_info_reply structure.
LIBVEM_API void vem_clear_reclaimInfoReply (vem_reclaim_info_reply_t *)
 Clear vem_reclaim_info_reply structure.
LIBVEM_API void vem_free_allocation_array (vem_allocation_t **, int)
 Free allocation structure array.
LIBVEM_API int vem_initialize_int (unsigned int)
 initialize vem library This function is called internally, user should use vem_initialize() only

Detailed Description

VEM Application Programming Interface.

Interfaces for allocating resources, executing workload containers, and information queries.


Define Documentation

#define VEM_REGISTER_TTL   (0x2)

This flag is used in vem_registerreq_t when the time to live (ttl) field is populated with the ttl value in minutes. If this flag is not set, the ttl value is ignored.

#define VEM_REGISTER_FORCE   (0x4)

This flag is used in vem_registerreq_t when an old client still exists in vemkd. Normally, if there is an existing client with the same name as the client in the registration call, the call would fail with VEME_NAME_INUSE since EGO enforces clients to have unique names. If this flag is used, the existing client will be disconnected and the new registration accepted.

#define DEF_CONTAINER_CONTROL_WAITPERIOD   60 * 2

value for controlWaitPeriod in container specification

#define VEM_REALLOC_DELTA   (0x1)

Used in flags of vem_reallocreq. If this bit is set in "flags" field, newMinSlot and newMaxSlot are interpreted as delta to orignal request rather than the default, which is interpreted as the new minimum and maximum required.

#define VEM_RELEASE_AUTOADJ   (0x1)

Used in vem_releasereq_t.

Automatically adjust maximum required to what is allocated. As a result no other resource will be allocated unless vem_realloc() is called. This is useful in scenarios where the allocated resource is more than required. It takes precedence over VEM_RELEASE_MODIFY if both are used together.

See also:
vem_releasereq_t

#define VEM_RELEASE_BLOCKED   (0x2)

Used in vem_releasereq_t

Block the released resources so that they will not be reallocated to this allocation. Useful when there is some application-specific problem that occurs when this resource is used. Once blacked, the resource will never be reallocated to this allocation. Use vem_unblock4alloc() to remove resources from blocked list.

See also:
vem_releasereq_t

#define VEM_RELEASE_MODIFY   (0x4)

Used in vem_releasereq_t

Automatically decrement the maximum required for this allocation by the number being released. If the minimum exceeds the maximum as a result of this, it is set equal to the maximum. It is useful in scenarios where there are unfulfilled requests in the allocation but the client is finished using the allocated one(s). It is superceeded by VEM_RELEASE_AUTOADJ if both are used together.

See also:
vem_releasereq_t

#define VEM_HOST_OK   0x0

VEM host status ready for alloc and exec

#define VEM_HOST_LIM_UNAVAIL   0x01

load collector unavailable

#define VEM_HOST_PEM_UNAVAIL   0x02

pem unavailable

#define VEM_HOST_PEM_FATAL   0x04

pem hangs or cannot start

#define VEM_HOST_UNLICENSE   0x08

host is unlicensed

#define VEM_HOST_LOCK_ADMIN   0x10

host is locked by admin

#define VEM_HOST_LOCK_WIND   0x20

host is locked by time wind

#define VEM_HOST_LOCK_MASTER   0x40

host is locked by master

#define VEM_HOST_LOCK_HPC   0x80

host is locked due to no cpu

#define VEM_HOST_BUSY   0x100

host is busy due to load

#define VEM_HOST_CLOSE_ADMIN   0x200

host is closed by admin

#define VEM_HOST_REMOVED   0x400

host removed from grid

#define VEM_HOST_CLOSE_RECLAIM_ADMIN   0x800

host is closed and reclaimed by administrator

#define VEM_HOST_CLOSE_RECLAIM_THRESHOLD   0x1000

host is closed and reclaimed by scavenging agent


Typedef Documentation

Possible message code received by client after connecting with VEM.

See also:
vem_message_t

typedef struct vem_message vem_message_t

Structure returned by vem_read() routine. The message contains a code that indicates what type of message it is, followed by possible message content.

These messages can be sent by VEM asynchronously. Client should check VEM handle using vem_select()/vem_read()periodically if callbacks are not used.

typedef struct vem_host vem_host_t

Used in allocation reply/reclaim to notify client how many slots on a given host are being allocated/reclaimed.

typedef struct vem_hostattr vem_hostattr_t

Used in allocation reply to give client some brief information about the host. If additional information about the host is required, client may use vem_getHostInfo() call to obtain them.

This message content corresponds to message code RESOURCE_ADD. It tells the client which host slot(s) are allocated for its use. This is a result of a previous vem_alloc() call by the client. The allocation ID returned from the orignal vem_alloc() call is indicated in this structure, so in case that client had made multiple allocation requests, it can distinguish between them.

See also:
vem_message_t

typedef struct vem_reclaim vem_reclaim_t

This is part of the vem_allocreclaim_t structure. It carries the details of which allocation and consumer is being reclaimed from, and which host slots VEM is trying to reclaim.

See also:
vem_allocreclaim_t

This message content corresponds to message code RESOURCE_RECLAIM. It tells the client which host slot(s) are being reclaimed. This message can possibly reclaim from multiple allocations.

See also:
vem_message_t

typedef struct vem_allocreq vem_allocreq_t

This structure is used while calling vem_alloc() to specify the allocation request.

This structure is used while calling vem_allocfree(). Freeing an allocation is the same as cancelling it. All allocated resources are reclaimed, and VEM will no longer allocate any resources to it.

This structure is part of vem_registerreq_t. It specifies the callback functions that should be used when a VEM message is received.

See also:
vem_registereq_t

This structure is used while calling vem_register().

typedef struct vem_openreq vem_openreq_t

This structure is used while calling vem_open().

typedef struct vem_handle vem_handle_t

This structure is returned from vem_open() call. Fields within this structure should not be accessed directly. This handle should be treated as opaque.

Note:
Special care is needed while populating rlimits field, VEM_RLIM_INFINITY should be used to indicate no limit, a value of zero really means zero, and often will create problems with container execution.

This structure is used in vem_startcontainer to request VEM to start a workload container.

This structure is used in vem_signalcontainer to request VEM to send a signal to an existing workload container.

This is part of the vem_container_info_reply_t structure.

See also:
vem_container_info_reply.

This is used in vem_register() when a recoverable client is being registered.

This is part of vem_allocation_info_reply_t structure

See also:
vem_allocation_info_reply_t

This is used in vem_register() when a recoverable client is being registered.

This is used in vem_register2() when a recoverable client is being registered.

This structure is used in vem_signalcontainer to request VEM to send a signal to an existing workload container.

This structure is used by vem_locate() to return information about registered clients.

This structure is used by vem_realloc()

This structure is used by vem_release.

typedef struct vem_hostinfo vem_hostinfo_t

This structure is returned from vem_getHostInfo() call.

This structure is used in vem_getHostInfo() call.

This structure is returned from vem_getHostSummary()

This structure is returned from vem_getMasterHostList()

This structure is returned from vem_getDefinedHostType


Enumeration Type Documentation

Possible message code received by client after connecting with VEM.

See also:
vem_message_t
Enumerator:
UNKNOWN_MSG  unknown message code
RESOURCE_ADD  message content will be "vem_allocreply_t"
RESOURCE_RECLAIM  message content will be "vem_allocreclaim_t"
CONTAINER_STATE_CHG  message content will be "vem_containerstatechg_t"
HOST_STATE_CHANGE  message content will be "vem_hoststatechg_t"

anonymous enum

These codes are used while calling vem_openbyname(), the vem_libparams->tstype should be set to one of the codes.

See also:
vem_openbyname

These are the possible values of the "exitReason" field in vem_container_t.

See also:
vem_container_t
Enumerator:
ER_NULL  0, no reason
ER_SETUP_NO_MEM  1, exit because of setup fail
ER_SETUP_FORK  2, fork fail
ER_SETUP_PGID  3, failed to setpgid
ER_SETUP_ENV  4, failed to set env variables
ER_SETUP_LIMIT  5, failed to set process limits
ER_SETUP_NO_USER  6, user account doesn't exist
ER_SETUP_PATH  7, failed to change container cwd
ER_SIG_KILL  8, terminated by sigkill
ER_UNKNOWN  9, unknown reason
ER_PEM_UNREACH  10, failed to reach pem host
ER_PEM_SYN  11, vemkd and pem sync issue
ER_NOSUCH_HOST  12, execution host is not a vem host
ER_NOSUCH_ALLOC  13, allocation doesn't exist
ER_BAD_ALLOC_HOST  14, host is not allocated
ER_NOSUCH_CLIENT  15, client doesn't exist
ER_START  16, container start fails
ER_NOSUCH_CMD  17, startup cmd does not exist
ER_CMD_EXEC  18, command cannot be executed
ER_JOBCTL_KILL  19, terminated by job controller
ER_JOBCTL_FAILED  20, terminated by SIGKILL, job controller does not exist or failed
LAST_EXIT_REASON  last exit reason

Enumerator:
DEBUG_VEMKD_ON  turn on vemkd debug
DEBUG_VEMKD_OFF  turn off vemkd debug
DEBUG_PEM_ON  turn on pem debug
DEBUG_PEM_OFF  turn off pem debug
DEBUG_LIM_ON  turn on lim debug
DEBUG_LIM_OFF  turn off lim debug


Function Documentation

LIBVEM_API vem_handle_t* vem_openbyname ( int  ,
struct vem_libparams  
)

Routine takes a list of master hostnames and port numbers to connect to. The API goes through the list, trying to set up connection with one of the master host. Once a connection is ready, the API returns the connection handler immediately.

Once a connection is ready, the API returns a handle immediately. This handle correspond to a connection with VEMKD, and will be used in subsequent communication with VEM.

Note:
The returned vem_handle should be treated as an opaque object.
Returns:
a handle, or NULL on error.

LIBVEM_API int vem_containerinfo ( struct vem_handle *  ,
vem_container_info_reply_t  
)

0 is returned. <0 otherwise.

LIBVEM_API int vem_get_avail_resources_for_consumer ( vem_handle_t ,
const char *  ,
const char *  ,
vem_avail_resources_t *   
)

Return available resources at the current moment for the specified consumer and hostgroup.

LIBVEM_API int vem_setpolicyparams ( vem_handle_t ,
vem_policy_params_t *   
)

Set parameters that control distribution behaviour



     
Date Modified: 26 Nov 2007
Platform Computing: www.platform.com

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

Copyright © 2001-2007 Platform Computing Corporation. All rights reserved.