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_t * vem_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_t * vem_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_t * vem_dup_allocreply (vem_allocreply_t *) Duplicate allocation reply message. LIBVEM_API vem_allocreclaim_t * vem_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
typedef enum vem_message_code vem_message_code_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.
typedef struct vem_allocreply vem_allocreply_t 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
typedef struct vem_allocreclaim 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.
typedef struct vem_allocfreereq vem_allocfreereq_t 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.
typedef struct vem_clientcallback vem_clientcallback_t 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
typedef struct vem_registerreq vem_registerreq_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.
typedef struct vem_container_spec vem_container_spec_t
- 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.
typedef struct vem_startcontainerreq vem_startcontainerreq_t This structure is used in vem_startcontainer to request VEM to start a workload container.
typedef struct vem_signalcontainerreq vem_signalcontainerreq_t This structure is used in vem_signalcontainer to request VEM to send a signal to an existing workload container.
typedef struct vem_container vem_container_t
typedef struct vem_container_info_reply vem_container_info_reply_t This is used in vem_register() when a recoverable client is being registered.
typedef struct vem_allocation vem_allocation_t
typedef struct vem_allocation_info_reply vem_allocation_info_reply_t This is used in vem_register() when a recoverable client is being registered.
typedef struct vem_reclaim_info_reply vem_reclaim_info_reply_t This is used in vem_register2() when a recoverable client is being registered.
typedef struct vem_allocinforeq vem_allocinforeq_t This structure is used in vem_signalcontainer to request VEM to send a signal to an existing workload container.
typedef struct vem_clientinfo vem_clientinfo_t This structure is used by vem_locate() to return information about registered clients.
typedef struct vem_reallocreq vem_reallocreq_t This structure is used by vem_realloc()
typedef struct vem_releasereq vem_releasereq_t This structure is used by vem_release.
typedef struct vem_hostinfo vem_hostinfo_t This structure is returned from vem_getHostInfo() call.
typedef struct vem_hostinforeq vem_hostinforeq_t This structure is used in vem_getHostInfo() call.
typedef struct vem_hostsummary vem_hostsummary_t This structure is returned from vem_getHostSummary()
typedef struct vem_masterlist vem_masterlist_t This structure is returned from vem_getMasterHostList()
typedef struct vem_hosttypes vem_hosttypes_t This structure is returned from vem_getDefinedHostType
Enumeration Type Documentation
enum vem_message_code
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:
enum vem_debug_code
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.