Eventmirror -- mirroring of master lists through event client interface
The event mirror interface provides a means to easily implement
Grid Engine components that need to have access to the masters
object lists and therefore have to mirror them.
Such components can be schedulers, proxies, monitoring tools etc.
It is designed as a layer above the event client interface.
Mirroring can be restricted to certain event types / object types.
Callback functions can be installed to perform actions additional to
pure mirroring.
Not yet operable on the usermapping related objects and lists.
Eventmirror -- mirroring of master lists through event client interface
typedef enum {
...
} sge_event_action;
typedef enum {
...
} sge_mirror_error;
typedef int (*sge_mirror_callback)(sge_object_type type,
sge_event_action action,
lListElem *event, void *clientdata);
The following types are defined for use with the event mirroring
interface:
Different event actions are defined in the enumeration sge_event_action:
SGE_EMA_LIST - the whole master list has been sent
(used at initialization)
SGE_EMA_ADD - a new object has been created
SGE_EMA_MOD - an object has been modified
SGE_EMA_DEL - an object has been deleted
SGE_EMA_TRIGGER - a certain action has been triggered,
e.g. a scheduling run or a shutdown.
Most functions of the event mirroring interface return error codes that
are defined in the enumeration sge_mirror_error:
SGE_EM_OK - action performed successfully
SGE_EM_NOT_INITIALIZED - the interface is not yet initialized
SGE_EM_BAD_ARG - some input parameter was incorrect
SGE_EM_TIMEOUT - a timeout occured
SGE_EM_DUPLICATE_KEY - an object should be added, but an object
with the same unique identifier already
exists.
SGE_EM_KEY_NOT_FOUND - an object with the given key was not found.
SGE_EM_CALLBACK_FAILED - a callback function failed
SGE_EM_PROCESS_ERRORS - an error occured during event processing
The event mirroring interface allows to install callback funktions for
actions on certain event types. These callback functions have to have
the same prototype as given by the function typedef sge_mirror_callback.
host_update_master_list() -- update the master hostlists
sge_callback_result rqs_update_master_list(object_description
*object_base, sge_object_type type, sge_event_action action, lListElem
*event, void *clientdata)
Update the global master lists of hosts
based on an event.
The function is called from the event mirroring interface.
Updates admin, submit or execution host list depending
on the event received.
object_description *object_base - base object
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
bool - true, if update is successfull, else false
The function should only be called from the event mirror interface.
ja_task_update_master_list() -- update array tasks of a job
bool
ja_task_update_master_list(sge_object_type type, sge_event_action action,
lListElem *event, void *clientdata)
Update the list of array tasks of a job
based on an event.
The function is called from the event mirroring interface.
An array tasks list of parallel tasks and the
scaled usage list are not updated in this function,
as this data is maintained by separate events.
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
bool - true, if update is successfull, else false
The function should only be called from the event mirror interface.
ja_task_update_master_list_usage() -- update an array tasks usage
bool
ja_task_update_master_list_usage(lList *job_list, lListElem *event)
Updates the scaled usage of an array task (also task data structure
of a non array job).
lListElem *event - event object containing the new usage list
lList *job_list - master job list
bool - true, if the operation succeeds, else false
job_update_master_list() -- update the master list of jobs
bool job_update_master_list(sge_object_type type,
sge_event_action action,
lListElem *event, void *clientdata)
Update the global master list of jobs
based on an event.
The function is called from the event mirroring interface.
A jobs array tasks are not updated by this function,
as they are maintained by separate events.
In addition, some scheduler specific attributes, that
are only used in scheduler, are not updated.
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
bool - true, if update is successfull, else false
The function should only be called from the event mirror interface.
job_update_master_list_usage() -- update usage for a jobs tasks
int job_update_master_list_usage(lListElem *event)
Events containing usage reports are sent for a jobs tasks.
This can be array tasks (where a non array job has a single
array task) or tasks of a parallel job.
This function decides which type of task has to receive
the updated usage report and passes the event
information to the corresponding update functions.
lListElem *event - event object containing the new usage list
lList *job_list - master job list
bool - true, if the operation succeeds, else false
pe_task_update_master_list() -- update parallel tasks of an array task
bool
pe_task_update_master_list(sge_object_type type, sge_event_action action,
lListElem *event, void *clientdata)
Update the list of parallel tasks of an array task
based on an event.
The function is called from the event mirroring interface.
The scaled usage list of a parallel task is not updated
by this function, as this data is maintained by a
separate event.
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
bool - true, if update is successfull, else false
The function should only be called from the event mirror interface.
pe_task_update_master_list_usage() -- update a parallel tasks usage
bool
pe_task_update_master_list_usage(lList *job_list, lListElem *event)
Updates the scaled usage of a parallel task.
lListElem *job_list - the master job list
lListElem *event - event object containing the new usage list
bool - true, if the operation succeeds, else false
schedd_conf_update_master_list() -- update the scheduler configuration
bool
schedd_conf_update_master_list(sge_object_type type,
sge_event_action action,
lListElem *event, void *clientdata)
Update the global master list of scheduler configurations
based on an event.
The function is called from the event mirroring interface.
The list only contains one element that is replaced when a
modify event arrives.
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
bool - true, if update is successfull, else false
The function should only be called from the event mirror interface.
sge_mirror_initialize() -- initialize a process local event mirror interface
sge_mirror_error sge_mirror_initialize(ev_registration_id id,
const char *name)
Initializes internal data structures and registers with qmaster
using the event client mechanisms.
Events covering shutdown requests and qmaster shutdown notification
are subscribed.
ev_registration_id id - id used to register with qmaster
const char *name - name used to register with qmaster a
bool use_global_date - if that to true, the implemenation is not thread
save anymore. This setting is to ensure, that
old code is still working, without beeing rewritten.
if false is put inhere, the mirror interface is
thread save. The current implementation has a limit,
which is, that only one thread can work on the mirror
data at a time, since it is stored as thread global.
event_client_update_func_t - a function which knows on how to handle new events.
The events are stored by this function and not send
out.
sge_mirror_error - SGE_EM_OK or an error code
sge_mirror_process_events() -- retrieve and process events
sge_mirror_error sge_mirror_process_events(void)
Retrieves new events from qmaster.
If new events have arrived from qmaster, they are processed,
that means, for each event
- if installed, a "before mirroring" callback is called
- the event is mirrored into the corresponding master list
- if installed, a "after mirroring" callback is called
If retrieving new events from qmaster fails over a time period
of 10 times the configured event delivery interval (see event
client interface, function ec_get_edtime), a timeout warning
is generated and a new registration of the event client is
prepared.
sge_mirror_error - SGE_EM_OK or an error code
sge_mirror_shutdown() -- shutdown mirroring
sge_mirror_error sge_mirror_shutdown(void)
Shuts down the event mirroring mechanism:
Unsubscribes all events, deletes contents of the corresponding
object lists and deregisteres from qmaster.
sge_mirror_error - SGE_EM_OK or error code
sge_mirror_strerror() -- map errorcode to error message
const char* sge_mirror_strerror(sge_mirror_error num)
Returns a string describing a given error number.
This function can be used to output error messages
if a function of the event mirror interface fails.
sge_mirror_error num - error number
const char* - corresponding error message
sge_mirror_subscribe() -- subscribe certain event types
sge_mirror_error sge_mirror_subscribe(sge_object_type type,
sge_mirror_callback callback_before,
sge_mirror_callback callback_after,
void *clientdata)
Subscribe a certain event type.
Callback functions can be specified, that can be executed before the
mirroring action and/or after the mirroring action.
The corresponding data structures are initialized,
the events associated with the event type are subscribed with the
event client interface.
lListElem *event client - event client to work with
sge_object_type type - event type to subscribe or
SGE_TYPE_ALL
sge_mirror_callback callback_before - callback to be executed before
mirroring
sge_mirror_callback callback_after - callback to be executed after
mirroring
void *clientdata - clientdata to be passed to the
callback functions
sge_mirror_error - SGE_EM_OK or an error code
sge_mirror_unsubscribe() -- unsubscribe event types
sge_mirror_error sge_mirror_unsubscribe(sge_object_type type)
Unsubscribes a certain event type or all if SGE_TYPE_ALL is given as type.
Unsubscribes the corresponding events in the underlying event client
interface and frees data stored in the corresponding mirrored list(s).
sge_object_type type - the event type to unsubscribe or SGE_TYPE_ALL
sge_mirror_error - SGE_EM_OK or an error code
sge_mirror_update_master_list() -- update a master list
sge_mirror_error sge_mirror_update_master_list(lList **list,
const lDescr *list_descr,
lListElem *ep,
const char *key,
sge_event_action action,
lListElem *event)
Updates a given master list according to the given event information.
The following actions are performed (depending on parameter action):
- SGE_EMA_LIST: an existing mirrored list is completely replaced
- SGE_EMA_ADD: a new element is added to the mirrored list
- SGE_EMA_MOD: a given element is modified
- SGE_EMA_DEL: a given element is deleted
lList **list - mirrored list to manipulate
lDescr *list_descr - descriptor of mirrored list
lListElem *ep - element to manipulate or NULL
const char *key - key of an element to manipulate
sge_event_action action - action to perform
lListElem *event - raw event
sge_mirror_error - SGE_EM_OK, or an error code
sge_mirror_update_master_list_host_key() -- update a master list
sge_mirror_error sge_mirror_update_master_list_host_key(lList **list,
const lDescr *list_descr,
int key_nm,
const char *key,
sge_event_action action,
lListElem *event)
Updates a certain element in a certain mirrored list.
Which element to update is specified by a given hostname.
lList **list - the master list to update
lDescr *list_descr - descriptor of the master list
int key_nm - field identifier of the key
const char *key - value of the key (a hostname)
sge_event_action action - action to perform on list
lListElem *event - raw event element
sge_mirror_error - SGE_EM_OK or an error code
sge_mirror_update_master_list_str_key() -- update a master list
sge_mirror_error sge_mirror_update_master_list_str_key(lList **list,
const lDescr *list_descr,
int key_nm,
const char *key,
sge_event_action action,
lListElem *event)
Updates a certain element in a certain mirrored list.
Which element to update is specified by a given string key.
lList **list - the master list to update
lDescr *list_descr - descriptor of the master list
int key_nm - field identifier of the key
const char *key - value of the key
sge_event_action action - action to perform on list
lListElem *event - raw event element
sge_mirror_error - SGE_EM_OK or an error code
sharetree_update_master_list() -- update the master sharetree list
bool
sharetree_update_master_list(sge_object_type type, sge_event_action action,
lListElem *event, void *clientdata)
Update the global master list for the sharetree
based on an event.
The function is called from the event mirroring interface.
Sharetree events always contain the whole sharetree, that
replaces an existing sharetree in the master list.
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
bool - true, if update is successfull, else false
The function should only be called from the event mirror interface.
ar_update_master_list() -- update the master advance reservation list
static sge_callback_result ar_update_master_list(sge_evc_class_t *evc,
object_description *object_base, sge_object_type type, sge_event_action
action, lListElem *event, void *clientdata)
Updates the global master list of advance reservations based on an event.
The function is called from the event mirroring interface.
sge_evc_class_t *evc - event client class
object_description *object_base - object base of master lists
sge_object_type type - event type
sge_event_action action - action to perform
lListElem *event - the raw event
void *clientdata - client data
static sge_callback_result - true, if update is successfull
false if an error occured
MT-NOTE: ar_update_master_list() is not MT safe
sge_mirror_update_master_list_ar_key() -- updates the advance reservation
master list
static sge_mirror_error sge_mirror_update_master_list_ar_key(lList
**list, const lDescr *list_descr, int key_nm, const char *key,
sge_event_action action, lListElem *event)
Updates a certain element in the advance reservation mirrored list. Which
element to update is specified by the given AR_id as string value
lList **list - the master list to update
const lDescr *list_descr - descriptor of the master list (AR_Type)
int key_nm - field identifies of the key (AR_name)
const char *key - AR_id as string value
sge_event_action action - action to perform on this list
lListElem *event - raw event element
static sge_mirror_error - SGE_EM_OK or an error code
MT-NOTE: sge_mirror_update_master_list_ar_key() is MT safe, needs GLOBAL_LOCK
--Eventmirror: Eventmirror --Eventmirror-Eventmirror-Typedefs: Eventmirror -Eventmirror-Typedefsar_update_master_list: sge_mirror ar_update_master_listhost_update_master_list: Eventmirror host host_update_master_listja_task_update_master_list: Eventmirror ja_task ja_task_update_master_listja_task_update_master_list_usage: Eventmirror ja_task ja_task_update_master_list_usagejob_update_master_list: Eventmirror job job_update_master_listjob_update_master_list_usage: Eventmirror job job_update_master_list_usagepe_task_update_master_list: Eventmirror pe_task pe_task_update_master_listpe_task_update_master_list_usage: Eventmirror pe_task pe_task_update_master_list_usageschedd_conf_update_master_list: Eventmirror schedd_conf schedd_conf_update_master_listsge_mirror_initialize: Eventmirror sge_mirror_initializesge_mirror_process_events: Eventmirror sge_mirror_process_eventssge_mirror_shutdown: Eventmirror sge_mirror_shutdownsge_mirror_strerror: Eventmirror sge_mirror_strerrorsge_mirror_subscribe: Eventmirror sge_mirror_subscribesge_mirror_unsubscribe: Eventmirror sge_mirror_unsubscribesge_mirror_update_master_list: Eventmirror sge_mirror_update_master_listsge_mirror_update_master_list_ar_key: sge_mirror sge_mirror_update_master_list_ar_keysge_mirror_update_master_list_host_key: Eventmirror sge_mirror_update_master_list_host_keysge_mirror_update_master_list_str_key: Eventmirror sge_mirror_update_master_list_str_keysharetree_update_master_list: Eventmirror sharetree sharetree_update_master_list