EV_Type -- event client object
SGE_ULONG(EV_id)
event client id (see Eventclient/-ID-numbers)
SGE_STRING(EV_name)
event client name (any string characterizing the client)
SGE_HOST(EV_host)
host on which the event client resides
SGE_STRING(EV_commproc)
addressing information
SGE_ULONG(EV_commid)
unique id of the event client in commd
SGE_ULONG(EV_uid)
user id under which the event client is running
SGE_ULONG(EV_d_time)
event delivery time (interval used by qmaster to deliver events)
SGE_List(EV_subscribed)
information about subscription and flushing
(see Eventclient/-Subscription and Eventclient/-Flushing)
SGE_ULONG(EV_busy_handling)
information about handling of busy states
(see Eventclient/-Busy-state)
SGE_ULONG(EV_last_heard_from)
time when qmaster heard from the event client for the last time
SGE_ULONG(EV_last_send_time)
time of the last delivery of events
SGE_ULONG(EV_next_send_time)
next time scheduled for the delivery of events
SGE_ULONG(EV_next_number)
next sequential number for events (each event gets a unique number)
SGE_ULONG(EV_busy)
is the event client busy? (0 = false, 1 = true)
no events will be delivered to a busy client
SGE_LIST(EV_events)
list of events - they will be spooled until the event client
acknowledges receipt
An event client creates and initializes such an object and passes
it to qmaster for registration.
Qmaster will fill some of the fields (e.g. the EV_id) and send
the object back to the event client on successful registration.
Whenever the event client wants to change some configuration
parameters, it changes the object and sends it to qmaster
with a modification request.
Qmaster uses the object internally to track sequential numbers,
delivery times, timeouts etc.
Evenclient -- The Grid Engine Event Client Interface
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 (e.g. jobs, queues, hosts)
and event types (e.g. add, modify, delete).
Flushing triggered by individual events can be set.
Policies can be set how to handle busy event clients.
Clients that receive large numbers of events or possibly take some
time for processing the events (e.g. depending on other components
like databases), should in any case make use of the busy handling.
The event client interface should have much less impact on qmaster
performance than polling the same data in regular intervals.
Busy-state -- Handling of busy event clients
An event client may have time periods where it is busy doing some
processing and can not accept new events.
In this case, qmaster should not send out new events but buffer them,
as otherwise timeouts would occur waiting for acknowledges.
Therefore an event client can set a policy that defines how busy
states are set and unset.
Which policy to use is set with the ev_set_busy_handling() function
call. The policy can be changed dynamically at runtime.
The following policies are implemented at present:
EV_BUSY_NO_HANDLING - busy state is not handled automatically
by the event client interface
EV_BUSY_UNTIL_ACK - when delivering events qmaster will set
the eventclient to busy and will unset
the busy state when the event client
acknowledges receipt of the events.
EV_BUSY_UNTIL_RELEASED - when delivering events qmaster will set
the eventclient to busy.
It will stay in the busy state until it
is explicitly released by the client
(calling ec_set_busy(0))
Events -- events available from qmaster
The following events can be raised in qmaster and be subscribed
by an event client:
sgeE_ALL_EVENTS
sgeE_ADMINHOST_LIST send admin host list at registration
sgeE_ADMINHOST_ADD event add admin host
sgeE_ADMINHOST_DEL event delete admin host
sgeE_ADMINHOST_MOD event modify admin host
sgeE_CALENDAR_LIST send calendar list at registration
sgeE_CALENDAR_ADD event add calendar
sgeE_CALENDAR_DEL event delete calendar
sgeE_CALENDAR_MOD event modify calendar
sgeE_CKPT_LIST send ckpt list at registration
sgeE_CKPT_ADD event add ckpt
sgeE_CKPT_DEL event delete ckpt
sgeE_CKPT_MOD event modify ckpt
sgeE_CENTRY_LIST send complex entry list at reg.
sgeE_CENTRY_ADD event add complex entry
sgeE_CENTRY_DEL event delete complex entry
sgeE_CENTRY_MOD event modify complex entry
sgeE_CONFIG_LIST send config list at registration
sgeE_CONFIG_ADD event add config
sgeE_CONFIG_DEL event delete config
sgeE_CONFIG_MOD event modify config
sgeE_EXECHOST_LIST send exec host list at registration
sgeE_EXECHOST_ADD event add exec host
sgeE_EXECHOST_DEL event delete exec host
sgeE_EXECHOST_MOD event modify exec host
sgeE_GLOBAL_CONFIG global config changed, replace by sgeE_CONFIG_MOD
sgeE_JATASK_ADD event add array job task
sgeE_JATASK_DEL event delete array job task
sgeE_JATASK_MOD event modify array job task
sgeE_PETASK_ADD, event add a new pe task
sgeE_PETASK_DEL, event delete a pe task
sgeE_JOB_LIST send job list at registration
sgeE_JOB_ADD event job add (new job)
sgeE_JOB_DEL event job delete
sgeE_JOB_MOD event job modify
sgeE_JOB_MOD_SCHED_PRIORITY event job modify priority
sgeE_JOB_USAGE event job online usage
sgeE_JOB_FINAL_USAGE event job final usage report after job end
sgeE_JOB_FINISH job finally finished or aborted (user view)
sgeE_JOB_SCHEDD_INFO_LIST send job schedd info list at registration
sgeE_JOB_SCHEDD_INFO_ADD event jobs schedd info added
sgeE_JOB_SCHEDD_INFO_DEL event jobs schedd info deleted
sgeE_JOB_SCHEDD_INFO_MOD event jobs schedd info modified
sgeE_MANAGER_LIST send manager list at registration
sgeE_MANAGER_ADD event add manager
sgeE_MANAGER_DEL event delete manager
sgeE_MANAGER_MOD event modify manager
sgeE_OPERATOR_LIST send operator list at registration
sgeE_OPERATOR_ADD event add operator
sgeE_OPERATOR_DEL event delete operator
sgeE_OPERATOR_MOD event modify operator
sgeE_NEW_SHARETREE replace possibly existing share tree
sgeE_PE_LIST send pe list at registration
sgeE_PE_ADD event pe add
sgeE_PE_DEL event pe delete
sgeE_PE_MOD event pe modify
sgeE_PROJECT_LIST send project list at registration
sgeE_PROJECT_ADD event project add
sgeE_PROJECT_DEL event project delete
sgeE_PROJECT_MOD event project modify
sgeE_QMASTER_GOES_DOWN qmaster notifies all event clients, before
it exits
sgeE_QUEUE_LIST send queue list at registration
sgeE_QUEUE_ADD event queue add
sgeE_QUEUE_DEL event queue delete
sgeE_QUEUE_MOD event queue modify
sgeE_QUEUE_SUSPEND_ON_SUB queue is suspended by subordinate mechanism
sgeE_QUEUE_UNSUSPEND_ON_SUB queue is unsuspended by subordinate mechanism
sgeE_SCHED_CONF replace existing (sge) scheduler configuration
sgeE_SCHEDDMONITOR trigger scheduling run
sgeE_SHUTDOWN request shutdown of an event client
sgeE_SUBMITHOST_LIST send submit host list at registration
sgeE_SUBMITHOST_ADD event add submit host
sgeE_SUBMITHOST_DEL event delete submit hostsource/libs/evc/sge_event_client.c
sgeE_SUBMITHOST_MOD event modify submit host
sgeE_USER_LIST send user list at registration
sgeE_USER_ADD event user add
sgeE_USER_DEL event user delete
sgeE_USER_MOD event user modify
sgeE_USERSET_LIST send userset list at registration
sgeE_USERSET_ADD event userset add
sgeE_USERSET_DEL event userset delete
sgeE_USERSET_MOD event userset modify
If user mapping is enabled (compile time option), the following
additional events can be subscribed:
sgeE_CUSER_ENTRY_LIST send list of user mappings
sgeE_CUSER_ENTRY_ADD a new user mapping was added
sgeE_CUSER_ENTRY_DEL a user mapping was deleted
sgeE_CUSER_ENTRY_MOD a user mapping entry was changed
sgeE_HGROUP_LIST send list of host groups
sgeE_HGROUP_ADD a host group was added
sgeE_HGROUP_DEL a host group was deleted
sgeE_HGROUP_MOD a host group was changed
This list of events will increase as further event situations
are identified and interfaced.
IF YOU ADD EVENTS HERE, ALSO UPDATE sge_mirror!
Flushing -- Configuration of event flushing
In the standard configuration, qmaster will deliver events
in certain intervals to event clients.
These intervals can be configured using the ec_set_edtime()
function call.
In certain cases, an event client will want to be immediately
notified, if certain events occur. A scheduler for example
could be notified immediately, if resources in a cluster become
available to allow instant refilling of the cluster.
The event client interface allows to configure flushing
for each individual event id.
Flushing can either be switched off (default) for an event, or
a delivery time can be configured.
If a delivery time is configured, events for the event client
will be delivered by qmaster at latest after this delivery time.
A delivery time of 0 means instant delivery.
Flushing can be changed dynamically at runtime through the
ec_set_flush/ec_unset_flush functions.
ID-numbers -- id numbers for registration
#include <sge_eventL.h>
Each event client registered at qmaster has a unique client id.
The request for registering at qmaster contains either a concrete
id the client wants to occupy, or it asks the qmaster to assign
an id.
The client sets the id to use at registration with the
ec_prepare_registration function call.
The following id's can be used:
EV_ID_ANY - qmaster will assign a unique id
EV_ID_SCHEDD - register at qmaster as scheduler
As long as an event client does not expect any special handling
within qmaster, it should let qmaster assign an id.
If a client expects special handling, a new id in the range
[2;10] has to be created and the special handling has to be
implemented in qmaster (probably in sge_event_master.c).
List filtering -- Configuration of the list filtering
The data sent with an event can be filtered on the master side.
Therefore one can set a where and what condition. If
all client data is removed via where condition, no event will
be send.
The method expects a lListElem representation of the lCondition
and lEnumeration. The two methods: "lWhatToElem" and
"lWhereToElem" will convert the structures.
One has to be carefull reducing the elements via what condition.
One has to ensure, that all elements have a custom descriptor
and that elements with different descriptors are not mixed in
the same list.
The master and client can benefit (in speed and memory consumption)
a lot by requesting only the data, the client actually needs.
All registered events for the same cull data structure need to have
the same what and where filter.
The JAT_Type list is handled special, because it is subscribable as
an event, and it is also a sub-structure in the JB_Type list. When
a JAT_Type filter is set, the JAT-Lists in the JB-List are filtered
as well.
Session filtering -- Filtering of events using a session key.
For JAPI event clients event subscription is not sufficient to
track only those events that are related to a JAPI session.
When session filtering is used the following rules are applied
to decide whether subscribed events are sent or not:
- Events that are associated with a specific session are not
sent when session filtering is used but the session does not
match.
- Events that are not associated with a specific session are
not sent. The only exception are total update events. If subscribed
these events are always sent and a more fine grained filtering is
applied.
Subscription -- Subscription interface for event clients
An event client is notified, if certain event conditions are
raised in qmaster.
Which events an event client is interested in can be set through
the subscription interface.
Events have a unique event identification that classifies them,
e.g. "a job has been submitted" or "a queue has been disabled".
Delivery of events can be switched on/off for each event id
individually.
Subscription can be changed dynamically at runtime through the
ec_subscribe/ec_unsubscribe functions.
Event Client Interface -- Client Functionality
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.
clients/qevent/qevent.c can serve as a simple example.
The scheduler (daemons/qmaster/sge_thread_scheduler.c)
is also implemented as (local) event client and uses all
mechanisms of the event client interface.
Global_Variables -- global variables in the client
static bool config_changed = false;
static bool need_register = true;
static lListElem *ec = NULL;
static u_long32 ec_reg_id = 0;
static u_long32 next_event = 1;
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
next_event - the sequence number of the next event we are waiting for
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.
ck_event_number() -- test event numbers
#include "evc/sge_event_client.h"
static bool
ck_event_number(lList *lp, u_long32 *waiting_for,
u_long32 *wrong_number)
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.
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
static bool - true on success, else false
ec_commit() -- commit configuration changes
#include "evc/sge_event_client.h"
bool
ec_commit(void)
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.
bool - true on success, else false
ec_commit() -- commit configuration changes via gdi multi request
#include "evc/sge_event_client.h"
int
ec_commit_multi(lList **malpp)
Similar to ec_commit configuration changes will be sent to qmaster.
But unless ec_commit which uses sge_gdi to send the change request,
ec_commit_multi uses a sge_gdi_multi call to send the configuration
change along with other gdi requests.
The ec_commit_multi call has to be the last request of the multi
request and will trigger the communication of the requests.
malpp - answer list for the whole gdi multi request
int - true on success, else false
ec_config_changed() -- tell system the config has changed
#include "evc/sge_event_client.h"
static void
ec_config_changed(void)
Checkes whether the configuration has changes.
Configuration changes can either be changes in the subscription
or change of the event delivery interval.
ec_deregister() -- deregister from the event server
#include "evc/sge_event_client.h"
int
ec_deregister(void)
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.
int - true, if the deregistration succeeded, else false
ec_get() -- look for new events
#include "evc/sge_event_client.h"
bool
ec_get(lList **event_list)
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.
lList **event_list - pointer to an event list to hold arriving
events
bool - true, if events or an empty event list was received, or
if no data was received within a certain time period
false, if an error occured
The event_list has to be freed by the calling function.
ec_get_busy() -- get the busy state
bool
ec_get_busy(void)
Reads the busy state of the event client.
bool - true: the client is busy, false: the client is idle
The function only returns the local busy state in the event
client itself. If this state changes, it will be reported to
qmaster with the next communication, but not back from
qmaster to the client.
ec_get_busy_handling() -- get configured busy handling policy
#include "evc/sge_event_client.h"
ev_busy_handling
ec_get_busy_handling(void)
Returns the policy currently configured.
ev_busy_handling - the current policy
ec_get_edtime() -- get the current event delivery interval
#include "evc/sge_event_client.h"
int
ec_get_edtime(void)
Get the interval qmaster will use to send events to the client.
int - the interval in seconds
ec_get_event_client() -- return lList *event_client cull list
lList *
ec_get_event_client(sge_evc_class_t *thiz)
return lList *event_client cull list
lList *event_client - NULL otherwise
ec_get_flush() -- get flushing information for an event
#include "evc/sge_event_client.h"
int
ec_get_flush(ev_event event)
An event client can request flushing of events from qmaster
for any number of the events subscribed.
This function returns the flushing information for an
individual event.
ev_event event - the event id to query
int - EV_NO_FLUSH or the number of seconds used for flushing
ec_get_flush_delay() -- get configured flush delay paramter
#include "evc/sge_event_client.h"
int
ec_get_flush_delay(void)
Returns the policy currently configured.
flush_delay - current flush delay parameter setting
ec_is_initialized() -- has the client been initialized
int
ec_is_initialized(void)
Checks if the event client mechanism has been initialized
(if ec_prepare_registration has been called).
int - true, if the event client interface has been initialized,
else false.
ec_mark4registration() -- new registration is required
#include "evc/sge_event_client.h"
void
ec_mark4registration(void)
Tells the event client mechanism, that the connection to the server
is broken and it has to reregister.
Should be no external interface. The event client mechanism should itself
detect such situations and react accordingly.
ec_need_new_registration() -- is a reregistration neccessary?
#include "evc/sge_event_client.h"
bool ec_need_new_registration(void)
Function to check, if a new registration at the server is neccessary.
bool - true, if the client has to (re)register, else false
ec_prepare_registration() -- prepare registration at server
#include "evc/sge_event_client.h"
bool
ec_prepare_registration(ev_registration_id id, const char *name)
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 Eventclient/-ID-numbers.
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.
ev_registration_id id - id used to register
const char *name - name of the event client
bool - true, if the function succeeded, else false
ec_register() -- register at the event server
#include "evc/sge_event_client.h"
bool
ec_register(void)
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.
bool - true, if the registration succeeded, else false
ec_set_busy() -- set the busy state
bool
ec_set_busy(bool busy)
Sets the busy state of the client. This has to be done if
the busy policy has been set to EV_BUSY_UNTIL_RELEASED.
An event client can set or unset the busy state at any time.
While it is marked busy at the qmaster, qmaster will not
deliver events to this client.
The changed busy state will be communicated to qmaster with
the next call to ec_commit (implicitly called by the next
ec_get).
bool busy - true = event client busy, true = event client idle
bool - true = success, false = failed
ec_set_edtime() -- set the event client busy handling
#include "evc/sge_event_client.h"
bool
ec_set_busy_handling(ev_busy_handling handling)
The event client interface has a mechanism to handle situations in which
an event client is busy and will not accept any new events.
The policy to use can be configured using this function.
For valid policies see ...
This parameter can be changed during runtime and will take effect
after a call to ec_commit or ec_get.
ev_busy_handling handling - the policy to use
bool - true, if the value was changed, else false
ec_set_edtime() -- set the event delivery interval
#include "evc/sge_event_client.h"
int
ec_set_edtime(int interval)
Set the interval qmaster will use to send events to the client.
Any number > 0 is a valid interval in seconds. However the interval
my not be larger than the commd commproc timeout. Otherwise the event
client encounters receive timeouts and this is returned as an error
by ec_get().
int interval - interval [s]
int - 1, if the value was changed, else 0
The maximum interval is limited to the commd commproc timeout.
The maximum interval should be limited also by the application.
A too big interval makes qmaster spool lots of events and consume
a lot of memory.
ec_set_flush() -- set flushing information for an event
#include "evc/sge_event_client.h"
bool
ec_set_flush(ev_event event, int flush)
An event client can request flushing of events from qmaster
for any number of the events subscribed.
This function sets the flushing information for an individual
event.
ev_event event - id of the event to configure
bool flush - true for flushing
int interval - flush interval in sec.
bool - true on success, else false
ec_set_flush_delay() -- set flush delay parameter
#include "evc/sge_event_client.h"
bool
ec_set_flush_delay(u_long32 flush_delay)
int flush_delay - flush delay parameter
bool - true, if the value was changed, else false
ec_subscribe() -- Subscribe an event
#include "evc/sge_event_client.h"
bool
ec_subscribe(ev_event event)
Subscribe a certain event.
See Eventclient/-Events 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.
ev_event event - the event number
bool - true on success, else false
ec_subscribe_all() -- subscribe all events
#include "evc/sge_event_client.h"
bool
ec_subscribe_all(void)
Subscribe all possible event.
The subscription will be in effect after calling ec_commit or ec_get.
bool - true on success, else false
Subscribing all events can cause a lot of traffic and may
decrease performance of qmaster.
Only subscribe all events, if you really need them.
ec_subscribe_flush() -- subscribe an event and set flushing
#include "evc/sge_event_client.h"
bool
ec_subscribe_flush(ev_event event, int flush)
Subscribes and event and configures flushing for this event.
ev_event event - id of the event to subscribe and flush
int flush - number of seconds between event creation
and flushing of events
bool - true on success, else false
ec_unset_flush() -- unset flushing information
#include "evc/sge_event_client.h"
bool
ec_unset_flush(ev_event event)
Switch of flushing of an individual event.
ev_event event - if of the event to configure
bool - true on success, else false
ec_unsubscribe() -- unsubscribe an event
#include "evc/sge_event_client.h"
bool
ec_unsubscribe(ev_event event)
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.
ev_event event - the event to unsubscribe
bool - true on success, else false
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.
ec_unsubscribe_all() -- unsubscribe all events
#include "evc/sge_event_client.h"
bool
ec_unsubscribe_all(void)
Unsubscribe all possible event.
The change will be in effect after calling ec_commit or ec_get.
bool - true on success, else false
The events sgeE_QMASTER_GOES_DOWN and sgeE_SHUTDOWN will not be
unsubscribed.
Defines -- Constants used in the module
#define EVENT_DELIVERY_INTERVAL_S 1
#define EVENT_DELIVERY_INTERVAL_N 0
#define EVENT_ACK_MIN_TIMEOUT 600
#define EVENT_ACK_MAX_TIMEOUT 1200
EVENT_DELIVERY_INTERVAL_S is the event delivery interval. It is set in seconds.
EVENT_DELIVERY_INTERVAL_N same thing but in nano seconds.
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).
add_list_event_for_client() -- add a list as event
#include "sge_event_master.h"
void
add_list_event_for_client(u_long32 event_client_id, u_long32 timestamp,
ev_event type, u_long32 intkey,
u_long32 intkey2, const char *strkey,
const char *session, lList *list)
Adds a list of objects to the list of events to deliver, e.g. the
sgeE*_LIST events, to a specific client. No checking is done to make
sure that the client id is valid. That is the responsibility of the
calling function.
u_long32 event_client_id - the id of the recipient
u_long32 timestamp - time stamp in gmt for the even; if 0 is passed,
sge_add_list_event will insert the actual time
ev_event type - the event id
u_long32 intkey - additional data
u_long32 intkey2 - additional data
const char *strkey - additional data
const char *session - events session key
lList *list - the list to deliver as event
Whether the event was added successfully.
MT-NOTE: add_list_event_for_client() is MT safe.
check_send_new_subscribed_list() -- check suscription for new list events
static void
check_send_new_subscribed_list(const subscription_t *old_subscription,
const subscription_t *new_subscription,
lListElem *event_client,
ev_event event)
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.
const subscription_t *old_subscription - former subscription
const subscription_t *new_subscription - new subscription
lListElem *event_client - the event client object
ev_event event - the event to check
object_description *master_table - master list table
eventclient_list_locate_by_adress() -- search event client by adress
#include "sge_event_master.h"
lListElem *
eventclient_list_locate_by_adress(const char *host,
const char *commproc, u_long32 id)
Searches the event client list for an event client with the
specified commlib adress.
Returns a pointer to the event client object or
NULL, if no such event client is registered.
const char *host - hostname of the event client to search
const char *commproc - commproc of the event client to search
u_long32 id - id of the event client to search
lListElem* - event client object or NULL.
eventclient_subscribed() -- has event client subscribed an event?
#include "sge_event_master.h"
int
eventclient_subscribed(const lListElem *event_client, ev_event event)
Checks if the given event client has a certain event subscribed.
For event clients that use session filtering additional conditions
must be fulfilled otherwise the event counts not as subscribed.
const lListElem *event_client - event client to check
ev_event event - event to check
const char *session - session key of this event
int - 0 = not subscribed, 1 = subscribed
sge_add_event() -- add an object as event
#include "sge_event_master.h"
void
sge_add_event(u_long32 timestamp, ev_event type,
u_long32 intkey, u_long32 intkey2,
const char *strkey, const char *strkey2,
const char *session, lListElem *element)
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().
u_long32 timestamp - event creation time, 0 -> use current time
ev_event type - the event id
u_long32 intkey - additional data
u_long32 intkey2 - additional data
const char *strkey - additional data
const char *strkey2 - additional data
const char *session - events session key
lListElem *element - the object to deliver as event
MT-NOTE: sge_add_event() is NOT MT safe.
sge_add_event_client() -- register a new event client
#include "sge_event_master.h"
int
sge_add_event_client(lListElem *clio, lList **alpp, lList **eclpp,
char *ruser, char *rhost)
Registeres a new event client.
If it requested a dynamic id, a new id is created and assigned.
If it is a special client(with fixed id) and an event client
with this id already exists, the old instance is deleted and the
new one registered.
If the registration succeeds, the event client is sent all data
(sgeE*_LIST events) according to its subscription.
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
event_client_update_func_t update_func - for internal event clients
monitoring_t monitor - monitoring handle
int - AN_status value. STATUS_OK on success, else error code
MT-NOTE: sge_add_event_client() is MT safe, it uses the global lock and
internal ones.
sge_add_list_event() -- add a list as event
#include "sge_event_master.h"
void
sge_add_list_event(u_long32 timestamp, ev_event type,
u_long32 intkey, u_long32 intkey2,
const char *strkey, const char *strkey2,
const char *session, lList *list)
Adds a list of objects to the list of events to deliver, e.g. the
sgeE*_LIST events.
u_long32 timestamp - event creation time, 0 -> use current time
ev_event type - the event id
u_long32 intkey - additional data
u_long32 intkey2 - additional data
const char *strkey - additional data
const char *strkey2 - additional data
const char *session - events session key
lList *list - the list to deliver as event
MT-NOTE: sge_add_list_event() is MT safe.
sge_add_list_event() -- add a list as event
#include "sge_event_master.h"
static lListElem* sge_create_event(u_long32 event_client_id,
u_long32 number,
u_long32 timestamp,
ev_event type,
u_long32 intkey,
u_long32 intkey2,
const char *strkey,
const char *strkey2,
const char *session,
lList *list)
Create ET_Type element and fill in the specified parameters.
The caller is responsible for freeing the memory again.
u_long32 event_client_id - event client id
u_long32 number - the event number
u_long32 timestamp - event creation time, 0 -> use current time
ev_event type - the event id
u_long32 intkey - additional data
u_long32 intkey2 - additional data
const char *strkey - additional data
const char *strkey2 - additional data
const char *session - events session key
lList *list - the list to deliver as event
MT-NOTE: sge_add_list_event() is MT safe.
sge_mod_event_client() -- modify event client
#include "sge_event_master.h"
int
sge_event_master_process_mod_event_client(lListElem *clio, lList **alpp,
lList **eclpp, char *ruser,
char *rhost)
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.
lListElem *clio - object containing the data to change
lList **alpp - answer list pointer
char *ruser - user that triggered the modify action
char *rhost - host that triggered the modify action
int - AN_status code. STATUS_OK on success, else error code
MT-NOTE: sge_mod_event_client() is NOT MT safe.
sge_handle_event_ack() -- acknowledge event delivery
#include "sge_event_master.h"
void
sge_handle_event_ack(u_long32 event_client_id, ev_event event_number)
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.
If the handling of a busy state of the event client is enabled and set to
EV_BUSY_UNTIL_ACK, the event client will be set to "not busy".
u_long32 event_client_id - event client sending acknowledge
ev_event event_number - serial number of the last event to acknowledge
bool - true on success, false on error
MT-NOTE: sge_handle_event_ack() is MT safe.
sge_has_event_client() -- Is a event client registered
#include "sge_event_master.h"
bool sge_has_event_client(u_long32 event_client_id)
Searches if the event client list, if a client
with this id is available
u_long32 event_client_id - id of the event client
bool - TRUE if client is in the event client list
MT-NOTE: sge_has_event_client() is MT safe, it uses the internal locks
sge_mod_event_client() -- modify event client
#include "sge_event_master.h"
int
sge_mod_event_client(lListElem *clio, lList **alpp, lList **eclpp,
char *ruser, char *rhost)
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.
lListElem *clio - object containing the data to change
lList **alpp - answer list pointer
char *ruser - user that triggered the modify action
char *rhost - host that triggered the modify action
int - AN_status code. STATUS_OK on success, else error code
MT-NOTE: sge_mod_event_client() is MT safe, uses internal locks
total_update() -- send all data to eventclient
static void
total_update(lListElem *event_client)
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.
lListElem *event_client - the event client to update
MT-NOTE: total_update() is MT safe, IF the function is invoked with
MT-NOTE: 'LOCK_EVENT_CLIENT_LST' locked! This is in accordance with
MT-NOTE: the acquire/release protocol as defined by the Grid Engine
MT-NOTE: Locking API.
MT-NOTE: the method also locks the global lock. One has to make sure,
MT-NOTE: that no calling method has that lock already.
total_update_event() -- create a total update event
static void
total_update_event(lListElem *event_client, ev_event type)
Creates an event delivering a certain list of objects for an event client.
For event clients that have subscribed a session list filtering can be done
here.
lListElem *event_client - event client to receive the list
ev_event type - event describing the list to update
object_description *object_base - master list table
event_text() -- deliver event description
const char* event_text(const lListElem *event)
Deliveres a short description of an event object.
const lListElem *event - the event to describe
const char* - pointer to the descriptive string.
The result points to a static buffer. Subsequent calls to
event_text will overwrite previous results.
build_subscription() -- generates an array out of the cull registration
structure
static void build_subscription(lListElem *event_el)
generates an array out of the cull registration
structure. The array contains all event elements and each of them
has an identifier, if it is subscribed or not. Before that is done, it is
tested, the EV_changed flag is set. If not, the function simply returns.
lListElem *event_el - the event element, which event structure will be transformed
init_send_events() -- sets the events, that should allways be delivered
void init_send_events()
sets the events, that should allways be delivered
MT-NOTE: init_send_events() is not MT safe
list_select() -- makes a reduced job list duplication
static bool list_select(subscription_t *subscription, int type, lList
**reduced_lp, lList *lp, const lCondition *selection, const lEnumeration
*fields, const lDescr *descr, bool do_hash)
Only works on job events. All others are ignored. The job events
need some special handling and this is done in this function. The
JAT_Type list can be subscribed by its self and it is also part
of the JB_Type. If a JAT_Type filter is set, this function also
filters the JAT_Type lists in the JB_Type lists.
subscription_t *subscription - subscription array
int type - event type
lList **reduced_lp - target list (has to be an empty list)
lList *lp - source list (will be modified)
const lCondition *selection - where filter
const lEnumeration *fields - what filter
const lDescr *descr - reduced descriptor
bool do_hash - create hash tables in the target list
static bool - true, if it was a job event
purge_event_list() -- purge event list
static int purge_event_list(lList* aList, ev_event event_number)
Remove all events from 'aList' which do have an event id less than or
equal to 'event_number'.
lList* aList - event list
ev_event event_number - event
int - number of events purged.
MT-NOTE: purge_event_list() is NOT MT safe.
MT-NOTE:
MT-NOTE: Do not call this function without having 'aList' locked!
BUGBUG-AD: If 'event_number' == 0, not events will be purged. However zero is
BUGBUG-AD: also the id of 'sgeE_ALL_EVENTS'. Is this behaviour correct?
sge_deliver_events_immediately() -- deliver events immediately
void sge_deliver_events_immediately(u_long32 event_client_id)
Deliver all events for the event client denoted by 'event_client_id'
immediately.
u_long32 event_client_id - event client id
void - none
MT-NOTE: sge_deliver_events_immediately() is NOT MT safe.
sge_event_master_init() -- event master initialization
static void sge_event_master_init(void)
Initialize the event master control structure. Initialize permanent
event array.
void - none
void - none
MT-NOTE: sge_event_master_init() is not MT safe
sge_event_master_send_events() -- send events to event clients
static void send_events(void)
Loop over all event clients and send events due. If an event client did
time out, it will be removed from the list of registered event clients.
Events will be delivered only, if the so called 'busy handling' of a
client does allow it. Events will be delivered as a report (REP_Type)
with a report list of type ET_Type.
lListElem *report - a report, has to be part of the report list. All
fields have to be init, except for REP_list element.
lList *report_list - a pre-init report list
void - none
MT-NOTE: send_events() is MT safe
MT-NOTE:
MT-NOTE: After all events for all clients have been sent. This function
MT-NOTE: will wait on the condition variable 'Event_Master_Control.cond_var'
sge_remove_event_client() -- remove event client
void sge_remove_event_client(u_long32 event_client_id)
Remove event client. Fetch event client from event client list.
Only sets status to "terminated",
it will be removed later on in ......................
u_long32 event_client_id - event client id
void - none
MT-NOTE: sge_remove_event_client() is MT safe, uses internal locks
sge_resync_schedd() -- resync schedd
int sge_resync_schedd(void)
Does a total update (send all lists) to schedd and outputs an error
message.
void - none
0 - resync successful
-1 - otherwise
MT-NOTE: sge_resync_schedd() in NOT MT safe.
sge_select_event_clients() -- select event clients
lList* sge_select_event_clients(const char *list_name, const lCondition
*where, const lEnumeration *what)
Select event clients.
const char *list_name - name of the result list returned.
const lCondition *where - where condition
const lEnumeration *what - what enumeration
lList* - list with elements of type 'EV_Type'.
MT-NOTE: sge_select_event_clients() is MT safe
MT-NOTE:
MT-NOTE: The elements contained in the result list are copies of the
MT-NOTE: respective event client list elements.
sge_shutdown_dynamic_event_clients() -- shutdown all dynamic event clients
int sge_shutdown_dynamic_event_clients(const char *anUser)
Shutdown all dynamic event clients. Each dynamic event client known will
be send a shutdown event.
An event client is a dynamic event client if it's client id is greater
than or equal to 'EV_ID_FIRST_DYNAMIC'.
Shutting down all dynamic event clients is only permitted if 'anUser' does
have manager privileges.
const char *anUser - user which did request this operation
lList **alpp - answer list for info and errors
EPERM - operation not permitted
0 - otherwise
MT-NOTES: sge_shutdown_dynamic_event_clients() is MT safe, it uses the
global_lock and internal ones.
sge_shutdown_event_client() -- shutdown an event client
int sge_shutdown_event_client(u_long32 event_client_id, const char* anUser,
uid_t anUID)
Shutdown an event client. Send the event client denoted by 'event_client_id'
a shutdown event.
Shutting down an event client is only permitted if 'anUser' does have
manager privileges OR is the owner of event client 'event_client_id'.
u_long32 event_client_id - event client ID
const char* anUser - user which did request this operation
uid_t anUID - user id of request user
lList **alpp - answer list for info and errors
EPERM - operation not permitted
ESRCH - client with given client id is unknown
0 - otherwise
MT-NOTE: sge_shutdown_event_client() is MT safe, it uses the global lock
and internal ones.
ec_get_id() -- Return event client id.
ev_registration_id ec_get_id(void)
Return event client id.
ev_registration_id - the event client id
ec_get_session() -- Get session key used for event filtering.
const char* ec_get_session(void)
Returns session key that is used in event master for event
filtering.
const char* - the session key
ec_mod_subscription_where() -- adds an element filter to the event
bool ec_mod_subscription_where(ev_event event, const lListElem *what,
const lListElem *where)
Allows to filter the event date on the master side to reduce the
date, which is send to the clients.
ev_event event - event type
const lListElem *what - what condition
const lListElem *where - where condition
bool - true, if everything went fine
ec_set_session() -- Specify session key for event filtering.
bool ec_set_session(const char *session)
Specifies a session that is used in event master for event
filtering.
const char *session - the session key
bool - true = success, false = failed
allocate_new_dynamic_id() -- gets a new dynamic id
static u_long32 allocate_new_dynamic_id(void)
Returns the next available dynamic event client id. The id returned will
be between EV_ID_FIRST_DYNAMIC and Event_Master_Control.max_event_clients +
EV_ID_FIRST_DYNAMIC.
The next available dynamic event client id.
MT-NOTE: allocate_new_dynamic_id() is thread safe,
when the caller holds Event_Master_Control.mutex.
blockEvents() -- blocks or unblocks events
void blockEvents(lListElem *event_client, int ev_type, bool isBlock)
In case that global update events have to be send, this function
blocks all events for that list, or unblocks it.
lListElem *event_client : event client to modify
ev_event ev_type : the event_lists to unblock or -1
bool isBlock : true: block events, false: unblock
MT-NOTE: sge_commit is thread safe.
elem_select() -- makes a reduced copy of an element with reducing sublists
as well
static lListElem *elem_select(subscription_t *subscription, lListElem *element,
const int ids[], const lCondition *selection,
const lEnumeration *fields, const lDescr *dp, int sub_type)
The function will apply the given filters for the element. Before the element
is reduced, all attribute sub lists named in "ids" will be removed from the list and
reduced. The reduced sub lists will be added the the reduced element and the original
element will be restored. The sub-lists will only be reduced, if the reduced element
still contains their attributes.
subscription_t *subscription - subscription array
lListElem *element - the element to reduce
const int ids[] - attribute with sublists to be reduced as well
const lCondition *selection - where filter
const lEnumeration *fields - what filter
const lDescr *descr - reduced descriptor
int sub_type - list type of the sublists.
bool - the reduced element, or NULL if something went wrong
NOTE:
MT-NOTE: works only on the variables -> thread save
getDescriptorL() -- returns a reduced desciptor
static const lDescr* getDescriptorL(subscription_t *subscription, const
lList* list, int type)
???
subscription_t *subscription - subscription array
const lList* list - source list
int type - event type
static const lDescr* - reduced descriptor or NULL, if no what exists
MT-NOTE: thread save, works only on the submitted variables.
get_event_client() -- gets the event client from the list
static lListElem *get_event_client(u_long32 id)
Returns the event client with the given id, or NULL if no such event
client exists.
u_long32 id - the client id
The event client with the given id, or NULL if no such event client
exists.
MT-NOTE: NOT thread safe. Requires caller to hold Event_Master_Control.mutex.
remove_event_client() -- removes an event client
static void
remove_event_client(lListElem **client, int event_client_id, bool lock_event_master)
removes an event client, marks the index as dirty and frees the memory
lListElem **client - event client to remove
int event_client_id - event client id to remove
bool lock_event_master - shall the function aquire the event_master mutex
MT-NOTE: remove_event_client() is not MT safe
- it locks the event master mutex to modify the event client list
- it assums that the event client is locked before this method is called
set_flush() -- Flush all events
void set_flush(void)
Flushes all pending events
MT-NOTE: set_flush is thread safe.
sge_add_event_for_client() -- add an event for a given object
bool
sge_add_event_for_client(u_long32 event_client_id, u_long32 timestamp, ev_event type,
u_long32 intkey, u_long32 intkey2,
const char *strkey, const char *strkey2,
const char *session, lListElem *element)
Add an event for a given event client.
u_long32 event_client_id - event client id
u_long32 timestamp - event creation time, 0 -> use current time
ev_event type - event id
u_long32 intkey - 1st numeric key
u_long32 intkey2 - 2nd numeric key
const char *strkey - 1st alphanumeric key
const char *strkey2 - 2nd alphanumeric key
const char *session - event session
lListElem *element - object to be delivered with the event
MT-NOTE: sge_add_event_for_client() is MT safe
sge_commit() -- Commit the queued events
bool sge_commit(void)
Sends any events that this thread currently has queued and clears the
queue.
Whether the call succeeded.
MT-NOTE: sge_commit is thread safe.
sge_event_master_wait_next() -- waits for a weakup
void sge_event_master_wait_next(void)
waits for a weakup
MT-NOTE: is MT safe
sge_get_max_dynamic_event_clients() -- get max dynamic event clients nr
u_long32 sge_get_max_dynamic_event_clients(u_long32 max)
Returns the actual value of max. dynamic event clients allowed.
u_long32 - max value
MT-NOTE: sge_get_max_dynamic_event_clients() is MT save
sge_set_commit_required() -- Require commits (make multipe object changes atomic)
void sge_set_commit_required()
Enables transactions on events. So far a rollback is not supported. It allows to accumulate
events, while multiple objects are modified and events are issued and to submit them as
one event package. There can only be one event session open at a time. The transaction_mutex
will block multiple calles to this method.
The method cannot be called recursivly, and sge_commit has to be called to close the transaction.
MT-NOTE: sge_set_commit_required is thread safe. Transactional event
processing is handled for each thread individually.
sge_set_max_dynamic_event_clients() -- set max number of dyn. event clients
void sge_set_max_dynamic_event_clients(u_long32 max)
Sets max number of dynamic event clients. If the new value is larger than
the maximum number of used file descriptors for communication this value
is set to the max. number of file descriptors minus some reserved file
descriptors. (10 for static event clients, 9 for execd, 10 for file
descriptors used by application (to write files, etc.) ).
At least one dynamic event client is allowed.
u_long32 max - number of dynamic event clients
MT-NOTE: sge_set_max_dynamic_event_clients() is MT safe
--EV_Type: Eventclient --EV_Type--Event_Client: Eventclient Client --Event_Client--Event_Client_Interface: Eventclient --Event_Client_Interface-Busy-state: Eventclient -Busy-state-Event_Client_Global_Variables: Eventclient Client -Event_Client_Global_Variables-Event_Client_Server_Defines: Eventclient Server -Event_Client_Server_Defines-Events: Eventclient -Events-Flushing: Eventclient -Flushing-ID-numbers: Eventclient -ID-numbers-List: Eventclient -List-Session: Eventclient -Session-Subscription: Eventclient -Subscriptionadd_list_event_for_client: Eventclient Server add_list_event_for_clientallocate_new_dynamic_id: sge_event_master allocate_new_dynamic_idblockEvents: sge_event_master blockEventsbuild_subscription: evm sge_event_master build_subscriptioncheck_send_new_subscribed_list: Eventclient Server check_send_new_subscribed_listck_event_number: Eventclient Client ck_event_numberec_commit: Eventclient Client ec_commitec_commit_multi: Eventclient Client ec_commit_multiec_config_changed: Eventclient Client ec_config_changedec_deregister: Eventclient Client ec_deregisterec_get: Eventclient Client ec_getec_get_busy: Eventclient Client ec_get_busyec_get_busy_handling: Eventclient Client ec_get_busy_handlingec_get_edtime: Eventclient Client ec_get_edtimeec_get_event_client: Eventclient Client ec_get_event_clientec_get_flush: Eventclient Client ec_get_flushec_get_flush_delay: Eventclient Client ec_get_flush_delayec_get_id: sge_event_client ec_get_idec_get_session: sge_event_client ec_get_sessionec_is_initialized: Eventclient Client ec_is_initializedec_mark4registration: Eventclient Client ec_mark4registrationec_mod_subscription_where: sge_event_client ec_mod_subscription_whereec_need_new_registration: Eventclient Client ec_need_new_registrationec_prepare_registration: Eventclient Client ec_prepare_registrationec_register: Eventclient Client ec_registerec_set_busy: Eventclient Client ec_set_busyec_set_busy_handling: Eventclient Client ec_set_busy_handlingec_set_edtime: Eventclient Client ec_set_edtimeec_set_flush: Eventclient Client ec_set_flushec_set_flush_delay: Eventclient Client ec_set_flush_delayec_set_session: sge_event_client ec_set_sessionec_subscribe: Eventclient Client ec_subscribeec_subscribe_all: Eventclient Client ec_subscribe_allec_subscribe_flush: Eventclient Client ec_subscribe_flushec_unset_flush: Eventclient Client ec_unset_flushec_unsubscribe: Eventclient Client ec_unsubscribeec_unsubscribe_all: Eventclient Client ec_unsubscribe_allelem_select: sge_event_master elem_selectevent_text: Eventclient event_texteventclient_list_locate: Eventclient Server eventclient_list_locateeventclient_subscribed: Eventclient Server eventclient_subscribedget_event_client: sge_event_master get_event_clientgetDescriptorL: sge_event_master getDescriptorLinit_send_events: evm sge_event_master init_send_eventslist_select: evm sge_event_master list_selectpurge_event_list: evm sge_event_master purge_event_listremove_event_client: sge_event_master remove_event_clientset_flush: sge_event_master set_flushsge_add_event: Eventclient Server sge_add_eventsge_add_event_client: Eventclient Server sge_add_event_clientsge_add_event_for_client: sge_event_master sge_add_event_for_clientsge_add_list_event: Eventclient Server sge_add_list_eventsge_commit: sge_event_master sge_commitsge_create_event: Eventclient Server sge_create_eventsge_deliver_events_immediately: evm sge_event_master sge_deliver_events_immediatelysge_event_master_init: evm sge_event_master sge_event_master_initsge_event_master_process_mod_event_client: Eventclient Server sge_event_master_process_mod_event_clientsge_event_master_send_events: evm sge_event_master sge_event_master_send_eventssge_event_master_wait_next: sge_event_master sge_event_master_wait_nextsge_get_max_dynamic_event_clients: sge_event_master sge_get_max_dynamic_event_clientssge_handle_event_ack: Eventclient Server sge_handle_event_acksge_has_event_client: Eventclient Server sge_has_event_clientsge_mod_event_client: Eventclient Server sge_mod_event_clientsge_remove_event_client: evm sge_event_master sge_remove_event_clientsge_resync_schedd: evm sge_event_master sge_resync_scheddsge_select_event_clients: evm sge_event_master sge_select_event_clientssge_set_commit_required: sge_event_master sge_set_commit_requiredsge_set_max_dynamic_event_clients: sge_event_master sge_set_max_dynamic_event_clientssge_shutdown_dynamic_event_clients: evm sge_event_master sge_shutdown_dynamic_event_clientssge_shutdown_event_client: evm sge_event_master sge_shutdown_event_clienttotal_update: Eventclient Server total_updatetotal_update_event: Eventclient Server total_update_event