1. Eventclient 1.1 --Introduction 1.2 Client 1.3 Server
Function Index
NAME
Evenclient -- The Grid Engine Event Client Interface |
FUNCTION
The Grid Engine Event Client Interface provides a means to connect to the Grid Engine qmaster and receive information about objects (actual object properties and changes). It provides a subscribe/unsubscribe mechanism allowing fine grained selection of objects per object types and event types (e.g. add, modify, delete). |
NOTES
The current implementation is a generalized form of the event client interface that already existed in Codine/GRD. It still contains code handling scheduler specific behavior, like the flushing of certain events. A further cleanup and generalization step should be done. The code should also be extracted from qmaster, scheduler and libsched directories and could form a new event client library. |
SEE ALSO
NAME
Event Client Interface -- Client Functionality |
SYNOPSIS
int ec_prepare_registration(u_long32 id, const char *name); int ec_register(void); int ec_deregister(void); int ec_subscribe(int event); int ec_subscribe_all(void); int ec_unsubscribe(int event); int ec_unsubscribe_all(void); int ec_set_edtime(int intval); int ec_get_edtime(void); int ec_commit(void); int ec_get(lList **); void ec_mark4registration(void); int ec_need_new_registration(void); |
FUNCTION
The client side of the event client interface provides functions to register and deregister (before registering, you have to call ec_prepare_registration to set an id and client name). The subscribe / unsubscribe mechanism allows to select the data (object types and events) an event client shall be sent. It is possible to set the interval in which qmaster will send new events to an event client. |
EXAMPLE
clients/qevent/qevent.c can serve as a simple example. The scheduler (daemons/schedd/sge_schedd.c) is also implemented as event client and uses all mechanisms of the event client interface. |
SEE ALSO
NAME
Global_Variables -- global variables in the client |
SYNOPSIS
static int config_changed = 0; static int need_register = 1; static lListElem *ec = NULL; static u_long32 ec_reg_id = 0; |
FUNCTION
config_changed - the configuration changed (subscription or event interval) need_register - the client is not registered at the server ec - event client object holding configuration data ec_reg_id - the id used to register at the qmaster |
NOTES
These global variables should be part of the event client object. The only remaining global variable would be a list of event client objects, allowing one client to connect to multiple event client servers. |
NAME
ck_event_number() -- test event numbers |
SYNOPSIS
static u_long32 ck_event_number(lList *lp, u_long32 *waiting_for, u_long32 *wrong_number) |
FUNCTION
Tests list of events if it contains right numbered events. Events with numbers lower than expected get trashed. In cases the master has added no new events to the event list and the acknowledge we sent was lost also a list with events lower than "waiting_for" is correct. But the number of the last event must be at least "waiting_for"-1. On success *waiting_for will contain the next number we wait for. On failure *waiting_for gets not changed and if wrong_number is not NULL *wrong_number contains the wrong number we got. |
INPUTS
lList *lp - event list to check u_long32 *waiting_for - next number to wait for u_long32 *wrong_number - event number that causes a failure |
RESULT
static u_long32 - 0 on success, else -1 |
NAME
ec_commit() -- commit configuration changes |
SYNOPSIS
int ec_commit(void) |
FUNCTION
Configuration changes (subscription and/or event delivery time) will be sent to the event server. The function should be called after (multiple) configuration changes have been made. If it is not explicitly called by the event client program, the next call of ec_get will commit configuration changes before looking for new events. |
RESULT
int - 1 on success, else 0 |
SEE ALSO
NAME
ec_config_changed() -- has the configuration changed? |
SYNOPSIS
static void ec_config_changed(void) |
FUNCTION
Checkes whether the configuration has changes. Configuration changes can either be changes in the subscription or change of the event delivery interval. |
RESULT
static void - 1, if the config has been changed, else 0 |
SEE ALSO
NAME
ec_deregister() -- deregister from the event server |
SYNOPSIS
int ec_deregister(void) |
FUNCTION
Deregister from the event server (usually the qmaster). This function should be called when an event client exits. If an event client does not deregister, qmaster will spool events for this client until it times out (it did not acknowledge events sent by qmaster). After the timeout, it will be deleted. |
RESULT
int - 1, if the deregistration succeeded, else 0 |
SEE ALSO
NAME
ec_get() -- look for new events |
SYNOPSIS
int ec_get(lList **event_list) |
FUNCTION
ec_get looks for new events. If new events have arrived, they are passed back to the caller in the parameter event_list. If the event client is not yet registered at the event server, the registration will be done before looking for events. If the configuration changed since the last call of ec_get and has not been committed, ec_commit will be called before looking for events. |
INPUTS
lList **event_list - pointer to an event list to hold arriving events |
RESULT
int - 0, if events or an empty event list was received, or if no data was received within a certain time period <0 (commlib error code), if an error occured |
NOTES
The event_list has to be freed by the calling function. |
SEE ALSO
NAME
ec_get_edtime() -- get the current event delivery interval |
SYNOPSIS
int ec_get_edtime(void) |
FUNCTION
Get the interval qmaster will use to send events to the client. |
RESULT
int - the interval in seconds |
SEE ALSO
NAME
ec_mark4registration() -- new registration is required |
SYNOPSIS
void ec_mark4registration(void) |
FUNCTION
Tells the event client mechanism, that the connection to the server is broken and it has to reregister. |
NOTES
Should be no external interface. The event client mechanism should itself detect such situations and react accordingly. Should not reference a global variable from scheduler (new_global_config)! |
SEE ALSO
NAME
ec_need_new_registration() -- is a reregistration neccessary |
SYNOPSIS
int ec_need_new_registration(void) |
FUNCTION
Function to check, if a new registration at the server is neccessary. |
RESULT
int - 1, if the client has to (re)register, else 0 |
NAME
ec_prepare_registration() -- prepare registration at server |
SYNOPSIS
int ec_prepare_registration(u_long32 id, const char *name) |
FUNCTION
Initializes necessary data structures and sets the data needed for registration at an event server. The events sgeE_QMASTER_GOES_DOWN and sgeE_SHUTDOWN are subscribed. For valid id's see .... The name is informational data that will be included in messages (errors, warnings, infos) and will be shown in the command line tool qconf -sec. |
INPUTS
u_long32 id - id used to register const char *name - name of the event client |
RESULT
int - 1,if the function succeeded, else 0 |
SEE ALSO
NAME
ec_register() -- register at the event server |
SYNOPSIS
int ec_register(void) |
FUNCTION
Registers the event client at the event server (usually the qmaster). This function can be called explicitly in the event client at startup or when the connection to qmaster is down. It will be called implicitly by ec_get, whenever it detects the neccessity to (re)register the client. |
RESULT
int - 1, if the registration succeeded, else 0 |
SEE ALSO
NAME
ec_set_edtime() -- set the event delivery interval |
SYNOPSIS
int ec_set_edtime(int interval) |
FUNCTION
Set the interval qmaster will use to send events to the client. Any number > 0 is a valid interval in seconds. |
INPUTS
int interval - interval [s] |
RESULT
int - 1, if the value was changed, else 0 |
NOTES
The maximum interval should be limited. A too big interval makes qmaster spool lots of events and consume a lot of memory. |
SEE ALSO
NAME
ec_subscribe() -- Subscribe an event |
SYNOPSIS
int ec_subscribe(int event) |
FUNCTION
Subscribe a certain event. See ... for a list of all events. The subscription will be in effect after calling ec_commit or ec_get. It is possible / sensible to subscribe all events wanted and then call ec_commit. |
INPUTS
int event - the event number |
RESULT
int - 1 on success, else 0 |
SEE ALSO
NAME
ec_subscribe_all() -- subscribe all events |
SYNOPSIS
int ec_subscribe_all(void) |
FUNCTION
Subscribe all possible event. The subscription will be in effect after calling ec_commit or ec_get. |
RESULT
int - 1 on success, else 0 |
NOTES
Subscribing all events can cause a lot of traffic and may decrease performance of qmaster. Only subscribe all events, if you really need them. |
SEE ALSO
NAME
ec_unsubscribe() -- unsubscribe an event |
SYNOPSIS
int ec_unsubscribe(int event) |
FUNCTION
Unsubscribe a certain event. See ... for a list of all events. The change will be in effect after calling ec_commit or ec_get. It is possible / sensible to unsubscribe all events no longer needed and then call ec_commit. |
INPUTS
int event - the event to unsubscribe |
RESULT
int - 1 on success, else 0 |
NOTES
The events sgeE_QMASTER_GOES_DOWN and sgeE_SHUTDOWN cannot be unsubscribed. ec_unsubscribe will output an error message if you try to unsubscribe sgeE_QMASTER_GOES_DOWN or sgeE_SHUTDOWN and return 0. |
SEE ALSO
NAME
ec_unsubscribe_all() -- unsubscribe all events |
SYNOPSIS
int ec_unsubscribe_all(void) |
FUNCTION
Unsubscribe all possible event. The change will be in effect after calling ec_commit or ec_get. |
RESULT
int - 1 on success, else 0 |
NOTES
The events sgeE_QMASTER_GOES_DOWN and sgeE_SHUTDOWN will not be unsubscribed. |
SEE ALSO
NAME
get_event_list() -- get event list via gdi call |
SYNOPSIS
static int get_event_list(int sync, lList **report_list) |
FUNCTION
Tries to retrieve the event list. Returns the incoming data and the commlib status/error code. This function is used by ec_get. |
INPUTS
int sync - synchronous transfer lList **report_list - pointer to returned list |
RESULT
static int - commlib status/error code |
SEE ALSO
NAME
Event Client Interface -- Server Functionality |
FUNCTION
The server module of the event client interface is used to integrate the capability to server event clients into server daemons. It is used in the Grid Engine qmaster but should be capable to handle any event client server integration. |
NOTES
The module still contains code specific to one event client, the scheduler. A further cleanup step should be done as suggested in Eventclient/--Introduction |
SEE ALSO
NAME
Defines -- Constants used in the module |
SYNOPSIS
#define FLUSH_INTERVAL 15 #define EVENT_ACK_MIN_TIMEOUT 600 #define EVENT_ACK_MAX_TIMEOUT 1200 |
FUNCTION
FLUSH_INTERVAL is the default event delivery interval, if the client would not set a correct interval. EVENT_ACK_MIN/MAX_TIMEOUT is the minimum/maximum timeout value for an event client sending the acknowledge for the delivery of events. The real timeout value depends on the event delivery interval for the event client (10 * event delivery interval). |
NAME
sge_flush_events() -- ??? |
SYNOPSIS
extern lList *Master_Adminhost_List; extern lList *Master_Calendar_List; extern lList *Master_Ckpt_List; extern lList *Master_Complex_List; extern lList *Master_Config_List; extern lList *Master_Exechost_List; extern lList *Master_Job_List; extern lList *Master_Job_Schedd_Info_List; extern lList *Master_Manager_List; extern lList *Master_Operator_List; extern lList *Master_Pe_List; extern lList *Master_Project_List; extern lList *Master_Queue_List; extern lList *Master_Sched_Config_List; extern lList *Master_Sharetree_List; extern lList *Master_Submithost_List; extern lList *Master_User_List; extern lList *Master_Userset_List; static int schedule_interval = FLUSH_INTERVAL; int last_seq_no = -1; int scheduler_busy = 0; lList *EV_Clients = NULL; |
FUNCTION
The extern lList's reference all object lists that can be used in a Grid Engine event client interface. schedule_interval, last_seq_no and scheduler_busy are used for scheduler specific handling. EV_Clients is a list of all event clients to the event server. |
NOTES
The scheduler specific handling (schedule_interval, last_seq_no and scheduler_busy) should be eliminated. The mechanisms implemented with these variables should be generally available for all event clients.# The same applies to the global variables flush_finish_sec and flush_submit_sec used in sge_flush_events. |
NAME
check_send_new_subscribed_list() -- check suscription for new list events |
SYNOPSIS
static void check_send_new_subscribed_list(const char *old_subscription, const char *new_subscription, lListElem *event_client, int event) |
FUNCTION
Checks, if sgeE*_LIST events have been added to the subscription of a certain event client. If yes, send these lists to the event client. |
INPUTS
const char *old_subscription - former subscription const char *new_subscription - new subscription lListElem *event_client - the event client object int event - the event to check |
SEE ALSO
NAME
ck_4_deliver_events() -- deliver events if necessary |
SYNOPSIS
void ck_4_deliver_events(u_long32 now) |
FUNCTION
Checks delivery time of each event client - if it has been reached, deliver all events for that client. In addition, timed out event clients are removed. An event client times out, if it doesn't acknowledge events within 10 * EV_ed_time (respecting EVENT_ACK_MIN_TIMEOUT and EVENT_ACK_MAX_TIMEOUT). |
INPUTS
u_long32 now - actual timestamp |
SEE ALSO
NAME
reinit_schedd() -- do a total update for the scheduler |
SYNOPSIS
void reinit_schedd() |
FUNCTION
Does a total update (send all lists) to the scheduler and output an error message. |
NOTES
This function should not be part of the core event client interface, it should perhaps be a commodity function or in qmaster itself. |
SEE ALSO
NAME
sge_ack_event() -- process acknowledge to event delivery |
SYNOPSIS
int sge_ack_event(lListElem *event_client, u_long32 event_number) |
FUNCTION
After the server sent events to an event client, it has to acknowledge their receipt. Acknowledged events are deleted from the list of events to deliver, otherwise they will be resent after the next event delivery interval. |
INPUTS
lListElem *event_client - event client sending acknowledge u_long32 event_number - serial number of the last event to acknowledge |
RESULT
int - always 0 |
NOTES
Returncode makes no sense anymore. Either improve error handling or make function return void. |
SEE ALSO
NAME
sge_add_event() -- add an object as event |
SYNOPSIS
void sge_add_event(lListElem *event_client, u_long32 type, u_long32 intkey, u_long32 intkey2, const char *strkey, lListElem *element) |
FUNCTION
Adds an object to the list of events to deliver. Called, if an event occurs to that object, e.g. it was added to Grid Engine, modified or deleted. Internally, a list with that single object is created and passed to sge_add_list_event(). |
INPUTS
lListElem *event_client - the event client to receive the event, if NULL, all event clients will receive the event u_long32 type - the event id u_long32 intkey - additional data u_long32 intkey2 - additional data const char *strkey - additional data lListElem *element - the object to deliver as event |
NOTES
Do we need the additional data fields? |
SEE ALSO
NAME
sge_add_event_client() -- register a new event client |
SYNOPSIS
int sge_add_event_client(lListElem *clio, lList **alpp, lList **eclpp, char *ruser, char *rhost) |
FUNCTION
Registeres a new event client. If it requested a dynamic id, a new id is created and assigned. If the registration succees, the event client is sent all data (sgeE*_LIST events) according to its subscription. |
INPUTS
lListElem *clio - the event client object used as registration data lList **alpp - answer list pointer for answer to event client lList **eclpp - list pointer to return new event client object char *ruser - user that tries to register an event client char *rhost - host on which the event client runs |
RESULT
int - AN_status value. STATUS_OK on success, else error code |
NOTES
Special handling for scheduler should be generalized in some way. |
SEE ALSO
NAME
sge_add_list_event() -- add a list as event |
SYNOPSIS
void sge_add_list_event(lListElem *event_client, u_long32 type, u_long32 intkey, u_long32 intkey2, const char *strkey, lList *list) |
FUNCTION
Adds a list of objects to the list of events to deliver, e.g. the sgeE*_LIST events. |
INPUTS
lListElem *event_client - the event client to receive the event, if NULL, all event clients will receive the event u_long32 type - the event id u_long32 intkey - additional data u_long32 intkey2 - additional data const char *strkey - additional data lList *list - the list to deliver as event |
NOTES
Do we need the additional data fields? |
SEE ALSO
NAME
sge_event_client_exit() -- event client deregisters |
SYNOPSIS
void sge_event_client_exit(const char *host, const char *commproc, sge_pack_buffer *pb) |
FUNCTION
Deregistration of an event client. The event client tells qmaster that it will wants to deregister - usually before it exits. The event client is removed from the list of all event clients. |
INPUTS
const char *host - host that sent the exit message const char *commproc - commproc of the sender sge_pack_buffer *pb - packbuffer containing information about event client |
NAME
sge_eventclient_subscribed() -- has event client subscribed a certain event? |
SYNOPSIS
int sge_eventclient_subscribed(const lListElem *event_client, int event) |
FUNCTION
Checks if the given event client has a certain event subscribed. |
INPUTS
const lListElem *event_client - event client to check int event - event to check |
RESULT
int - 0 = not subscribed, 1 = subscribed |
NAME
sge_flush_events() -- set the flushing time for events |
SYNOPSIS
void sge_flush_events(lListElem *event_client, int cmd) |
FUNCTION
Sets the timestamp for the next flush of events for all or a specific event client. When events will be next sent to an event client is stored in its event client object in the variable EV_next_send_time. |
INPUTS
lListElem *event_client - the event client for which to define flushing, or NULL (flush all event clients) int cmd - how to flush: FLUSH_EVENTS_SET: flush immediately; send events when the server triggers the next sending FLUSH_EVENTS_JOB_FINISHED: flush after the interval defined in flush_finish_sec FLUSH_EVENTS_JOB_SUBMITTED: flush after the interval defined in flush_submit_sec |
NOTES
The global variables flush_finish_sec and flush_submit_sec should be eliminated and replaced by a more general mechanism, where each event client can define individually, which event will trigger which flushing behaviour. |
SEE ALSO
NAME
sge_gdi_kill_eventclient() -- kill an event client |
SYNOPSIS
void sge_gdi_kill_eventclient(const char *host, sge_gdi_request *request, sge_gdi_request *answer) |
FUNCTION
Kills one or all dynamic event clients. If a certain event client id is contained in the request, an event client with that id is killed. If the requested id is EC_ID_ANY (0), all event clients with dynamic ids are killed. Killing an event client is done by sending it the special event sgeE_SHUTDOWN and flushing immediately. |
INPUTS
const char *host - host that sent the kill request sge_gdi_request *request - request containing the event client id sge_gdi_request *answer - answer structure to return an answer to the client issuing the kill command (usually qconf) |
SEE ALSO
NAME
sge_gdi_tsm() -- trigger scheduling |
SYNOPSIS
void sge_gdi_tsm(char *host, sge_gdi_request *request, sge_gdi_request *answer) |
FUNCTION
Triggers a scheduling run for the scheduler as special event client. |
INPUTS
char *host - host that triggered scheduling sge_gdi_request *request - request structure sge_gdi_request *answer - answer structure to return to client |
NOTES
This function should not be part of the core event client interface. |
SEE ALSO
NAME
sge_get_next_event_number() -- next event number for an event client |
SYNOPSIS
u_long32 sge_get_next_event_number(u_long32 client_id) |
FUNCTION
Retrieves the next serial event number for an event client. |
INPUTS
u_long32 client_id - id of the event client |
RESULT
u_long32 - serial number for next event to deliver |
NAME
sge_locate_scheduler() -- search for the scheduler |
SYNOPSIS
lListElem* sge_locate_scheduler() |
FUNCTION
Searches an event client of type scheduler (EV_ID_SCHEDD). Returns a pointer to the scheduler event client object or NULL, if no scheduler is registered as event client. |
RESULT
lListElem* - scheduler event client object or NULL. |
NOTES
Should not be part of the core event client interface. Might be provided in a more general form (for any special event client) as commodity function. |
NAME
sge_mod_event_client() -- modify event client |
SYNOPSIS
int sge_mod_event_client(lListElem *clio, lList **alpp, lList **eclpp, char *ruser, char *rhost) |
FUNCTION
An event client object is modified. It is possible to modify the event delivery time and the subscription. If the subscription is changed, and new sgeE*_LIST events are subscribed, these lists are sent to the event client. |
INPUTS
lListElem *clio - object containing the data to change lList **alpp - answer list pointer lList **eclpp - list pointer to return changed object char *ruser - user that triggered the modify action char *rhost - host that triggered the modify action |
RESULT
int - AN_status code. STATUS_OK on success, else error code |
SEE ALSO
NAME
sge_next_flush() -- when will be the next flush of events? |
SYNOPSIS
int sge_next_flush(int now) |
FUNCTION
Returns the timestamp of the next required flush to any event client (the minimum of EV_next_send_time for all event clients). |
INPUTS
int now - actual timestamp |
RESULT
int - the timestamp of the next flush or 0, if no event client is connected and up. |
NAME
sge_total_update_event() -- create a total update event |
SYNOPSIS
static void sge_total_update_event(lListElem *event_client, u_long32 type) |
FUNCTION
Creates an event delivering a certain list of objects for an event client. |
INPUTS
lListElem *event_client - event client to receive the list u_long32 type - event describing the list to update |
NAME
total_update() -- send all data to eventclient |
SYNOPSIS
static void total_update(lListElem *event_client) |
FUNCTION
Sends all complete lists it subscribed to an eventclient. If the event client receives a complete list instead of single events, it should completely update it's database. |
INPUTS
lListElem *event_client - the event client to update |
Jump to: | C E G R S T |
---|
Jump to: | C E G R S T |
---|
[Top] | [Contents] | [Index] | [ ? ] |
1. Eventclient
1.1 --IntroductionFunction Index
1.2 Client
1.2.1 --Introduction1.3 Server
1.2.2 -Global_Variables
1.2.3 ck_event_number
1.2.4 ec_commit
1.2.5 ec_config_changed
1.2.6 ec_deregister
1.2.7 ec_get
1.2.8 ec_get_edtime
1.2.9 ec_mark4registration
1.2.10 ec_need_new_registration
1.2.11 ec_prepare_registration
1.2.12 ec_register
1.2.13 ec_set_edtime
1.2.14 ec_subscribe
1.2.15 ec_subscribe_all
1.2.16 ec_unsubscribe
1.2.17 ec_unsubscribe_all
1.2.18 get_event_list
1.3.1 --Introduction
1.3.2 -Defines
1.3.3 -Global_Variables
1.3.4 check_send_new_subscribed_list
1.3.5 ck_4_deliver_events
1.3.6 reinit_schedd
1.3.7 sge_ack_event
1.3.8 sge_add_event
1.3.9 sge_add_event_client
1.3.10 sge_add_list_event
1.3.11 sge_event_client_exit
1.3.12 sge_eventclient_subscribed
1.3.13 sge_flush_events
1.3.14 sge_gdi_kill_eventclient
1.3.15 sge_gdi_tsm
1.3.16 sge_get_next_event_number
1.3.17 sge_locate_scheduler
1.3.18 sge_mod_event_client
1.3.19 sge_next_flush
1.3.20 sge_total_update_event
1.3.21 total_update
[Top] | [Contents] | [Index] | [ ? ] |
1. Eventclient
Function Index
[Top] | [Contents] | [Index] | [ ? ] |
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ < ] | Back | previous section in reading order | 1.2.2 |
[ > ] | Forward | next section in reading order | 1.2.4 |
[ << ] | FastBack | previous or up-and-previous section | 1.1 |
[ Up ] | Up | up section | 1.2 |
[ >> ] | FastForward | next or up-and-next section | 1.3 |
[Top] | Top | cover (top) of document | |
[Contents] | Contents | table of contents | |
[Index] | Index | concept index | |
[ ? ] | About | this page |