Autodocs for <CODE>Event Client Interface</CODE>:

[Top] | [Contents] | [Index] | [ ? ]

# Autodocs for `Event Client Interface`

This document describes `Event Client Interface` version SGE pre6.0 (Maintrunk).

Copyright © The Grid Engine Team

> 1. Eventclient |  |
> 1.1 --EV_Type |  |
> 1.2 --Event_Client_Interface |  |
> 1.3 -Busy-state |  |
> 1.4 -Events |  |
> 1.5 -Flushing |  |
> 1.6 -ID-numbers |  |
> 1.7 -Subscription |  |
> 1.8 Client |  |
> 1.9 Server |  |
> 1.10 event_text |  |

> Function Index |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 1. Eventclient

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.1 --EV_Type

NAME

      EV_Type -- event client object

ELEMENTS

      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_STRING(EV_subscription)
         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

      SGE_ULONG(EV_clientdata)
         a 32bit ulong for use by the event client or special handling
         for certain event clients

FUNCTION

      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.

SEE ALSO
  - 1.2 --Event_Client_Interface.
  - 1.6 -ID-numbers.
  - 1.7 -Subscription.
  - 1.5 -Flushing.
  - 1.3 -Busy-state.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.2 --Event_Client_Interface

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 (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.

NOTES

      The current implementation is a generalized form of the event client
      interface that already existed in Codine/GRD.

SEE ALSO
  - 1.1 --EV_Type.
  - 1.7 -Subscription.
  - 1.5 -Flushing.
  - 1.3 -Busy-state.
  - 1.8.1 --Event_Client.
  - 1.9.1 --Event_Client_Server.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.3 -Busy-state

NAME

      Busy-state -- Handling of busy event clients

FUNCTION

      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 spool them,
      as otherwise timeouts would occur waiting for acknowledges.

      Therefore an event client can set a policy that describes 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))

SEE ALSO
  - 1.8.20 ec_set_busy_handling.
  - 1.8.19 ec_set_busy.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.4 -Events

NAME

      Events -- events available from qmaster

FUNCTION

      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_COMPLEX_LIST                send complex list at registration
         sgeE_COMPLEX_ADD                 event add complex
         sgeE_COMPLEX_DEL                 event delete complex
         sgeE_COMPLEX_MOD                 event modify complex

         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 host
         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_USERMAPPING_ENTRY_LIST      send list of user mappings
         sgeE_USERMAPPING_ENTRY_ADD       a new user mapping was added
         sgeE_USERMAPPING_ENTRY_DEL       a user mapping was deleted
         sgeE_USERMAPPING_ENTRY_MOD       a user mapping entry was changed

         sgeE_HOST_GROUP_LIST             send list of host groups
         sgeE_HOST_GROUP_ADD              a host group was added
         sgeE_HOST_GROUP_DEL              a host group was deleted
         sgeE_HOST_GROUP_MOD              a host group was changed

NOTES

      This list of events will increase as further event situations
      are identified and interfaced.

      IF YOU ADD EVENTS HERE, ALSO UPDATE sge_mirror!

SEE ALSO
  - 1.7 -Subscription.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.5 -Flushing

NAME

      Flushing -- Configuration of event flushing

FUNCTION

      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.

SEE ALSO
  - 1.8.22 ec_set_edtime.
  - 1.8.23 ec_set_flush.
  - 1.8.27 ec_unset_flush.
  - 1.8.26 ec_subscribe_flush.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.6 -ID-numbers

NAME

      ID-numbers -- id numbers for registration

SYNOPSIS

      #include <sge_eventL.h>

FUNCTION

      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

NOTES

      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).

SEE ALSO
  - 1.8.17 ec_prepare_registration.
  - 1.9.10 sge_add_event_client.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.7 -Subscription

NAME

      Subscription -- Subscription interface for event clients

FUNCTION

      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.

SEE ALSO
  - 1.4 -Events.
  - 1.8.24 ec_subscribe.
  - 1.8.25 ec_subscribe_all.
  - 1.8.28 ec_unsubscribe.
  - 1.8.29 ec_unsubscribe_all.
  - 1.8.26 ec_subscribe_flush.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.8 Client

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.1 --Event_Client

NAME

      Event Client Interface -- Client Functionality

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
  - 1.2 --Event_Client_Interface.
  - 1.8.17 ec_prepare_registration.
  - 1.8.18 ec_register.
  - 1.8.7 ec_deregister.
  - 1.8.24 ec_subscribe.
  - 1.8.25 ec_subscribe_all.
  - 1.8.28 ec_unsubscribe.
  - 1.8.29 ec_unsubscribe_all.
  - 1.8.13 ec_get_flush.
  - 1.8.23 ec_set_flush.
  - 1.8.27 ec_unset_flush.
  - 1.8.26 ec_subscribe_flush.
  - 1.8.22 ec_set_edtime.
  - 1.8.12 ec_get_edtime.
  - 1.8.20 ec_set_busy_handling.
  - 1.8.10 ec_get_busy_handling.
  - 1.8.21 ec_set_clientdata.
  - 1.8.11 ec_get_clientdata.
  - 1.8.4 ec_commit.
  - 1.8.8 ec_get.
  - 1.8.15 ec_mark4registration.
  - 1.8.16 ec_need_new_registration.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.2 -Event_Client_Global_Variables

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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.3 ck_event_number

NAME

      ck_event_number() -- test event numbers

SYNOPSIS

      #include "sge_event_client.h"

      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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.4 ec_commit

NAME

      ec_commit() -- commit configuration changes

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.5 ec_commit_multi.
  - 1.8.6 ec_config_changed.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.5 ec_commit_multi

NAME

      ec_commit() -- commit configuration changes via gdi multi request

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_commit_multi(lList **malpp)

FUNCTION

      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.

INPUTS

      malpp - answer list for the whole gdi multi request

RESULT

      int - true on success, else false

SEE ALSO
  - 1.8.4 ec_commit.
  - 1.8.6 ec_config_changed.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.6 ec_config_changed

NAME

      ec_config_changed() -- tell system the config has changed

SYNOPSIS

      #include "sge_event_client.h"

      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.

SEE ALSO
  - 1.8.24 ec_subscribe.
  - 1.8.25 ec_subscribe_all.
  - 1.8.28 ec_unsubscribe.
  - 1.8.29 ec_unsubscribe_all.
  - 1.8.22 ec_set_edtime.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.7 ec_deregister

NAME

      ec_deregister() -- deregister from the event server

SYNOPSIS

      #include "sge_event_client.h"

      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 - true, if the deregistration succeeded, else false

SEE ALSO
  - 1.8.18 ec_register.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.8 ec_get

NAME

      ec_get() -- look for new events

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.18 ec_register.
  - 1.8.4 ec_commit.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.9 ec_get_busy

NAME

      ec_get_busy() -- get the busy state

SYNOPSIS

      int
      ec_get_busy(void)

FUNCTION

      Reads the busy state of the event client.

RESULT

      int - 1: the client is busy, 0: the client is idle

NOTES

      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.

SEE ALSO
  - 1.3 -Busy-state.
  - 1.8.20 ec_set_busy_handling.
  - 1.8.19 ec_set_busy.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.10 ec_get_busy_handling

NAME

      ec_get_busy_handling() -- get configured busy handling policy

SYNOPSIS

      #include "sge_event_client.h"

      ev_busy_handling
      ec_get_busy_handling(void)

FUNCTION

      Returns the policy currently configured.

RESULT

      ev_busy_handling - the current policy

SEE ALSO
  - 1.8.22 ec_set_edtime.
  - 1.3 -Busy-state.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.11 ec_get_clientdata

NAME

      ec_get_clientdata() -- get the clientdata value

SYNOPSIS

      #include "sge_event_client.h"

      u_long32
      ec_get_clientdata()

FUNCTION

      Get the current value of the clientdata for the event client.

RESULT

      u_long32 - current value

SEE ALSO
  - 1.8.11 ec_get_clientdata.
  - See ``Eventclient/EV_Type`'

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.12 ec_get_edtime

NAME

      ec_get_edtime() -- get the current event delivery interval

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.22 ec_set_edtime.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.13 ec_get_flush

NAME

      ec_get_flush() -- get flushing information for an event

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_get_flush(ev_event event)

FUNCTION

      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.

INPUTS

      ev_event event - the event id to query

RESULT

      int - EV_NO_FLUSH(-1) or the number of seconds used for flushing

SEE ALSO
  - 1.5 -Flushing.
  - 1.8.23 ec_set_flush.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.14 ec_is_initialized

NAME

      ec_is_initialized() -- has the client been initialized

SYNOPSIS

      int
      ec_is_initialized(void)

FUNCTION

      Checks if the event client mechanism has been initialized
      (if ec_prepare_registration has been called).

RESULT

      int - true, if the event client interface has been initialized,
            else false.

SEE ALSO
  - 1.8.17 ec_prepare_registration.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.15 ec_mark4registration

NAME

      ec_mark4registration() -- new registration is required

SYNOPSIS

      #include "sge_event_client.h"

      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.

SEE ALSO
  - 1.8.16 ec_need_new_registration.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.16 ec_need_new_registration

NAME

      ec_need_new_registration() -- is a reregistration neccessary?

SYNOPSIS

      #include "sge_event_client.h"

      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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.17 ec_prepare_registration

NAME

      ec_prepare_registration() -- prepare registration at server

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_prepare_registration(ev_registration_id 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 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.

INPUTS

      ev_registration_id id  - id used to register
      const char *name       - name of the event client

RESULT

      int - 1, if the function succeeded, else 0

SEE ALSO
  - 1.1 --EV_Type.
  - 1.6 -ID-numbers.
  - 1.7 -Subscription.
  - See ``qconf`'
  - See ``manpage`'
  - See ``list`'
  - See ``of`'
  - See ``events`'

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.18 ec_register

NAME

      ec_register() -- register at the event server

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.7 ec_deregister.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.19 ec_set_busy

NAME

      ec_set_busy() -- set the busy state

SYNOPSIS

      int
      ec_set_busy(int busy)

FUNCTION

      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).

INPUTS

      int busy - 1 = event client busy, 0 = event client idle

RESULT

      int - 1 = success, 0 = failed

SEE ALSO
  - 1.3 -Busy-state.
  - 1.8.20 ec_set_busy_handling.
  - 1.8.9 ec_get_busy.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.20 ec_set_busy_handling

NAME

      ec_set_edtime() -- set the event client busy handling

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_set_busy_handling(ev_busy_handling handling)

FUNCTION

      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.

INPUTS

      ev_busy_handling handling - the policy to use

RESULT

      int - 1, if the value was changed, else 0

SEE ALSO
  - 1.8.10 ec_get_busy_handling.
  - 1.3 -Busy-state.
  - 1.8.4 ec_commit.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.21 ec_set_clientdata

NAME

      ec_set_clientdata() -- set the clientdata value

SYNOPSIS

      #include "sge_event_client.h"

      void
      ec_set_clientdata(u_long32 data)

FUNCTION

      An event client (the event client object) has a field EV_clientdata.
      It is of datatype u_long32 and can be used by the event client for
      any purpose.

      The sge scheduler uses it to store the last order from scheduler processed
      by qmaster.

INPUTS

      u_long32 data - the clientdata to set

SEE ALSO
  - 1.8.11 ec_get_clientdata.
  - 1.1 --EV_Type.
  - See ``documentation`'
  - See ``of`'
  - See ``scheduler`'
  - See ``-`'
  - See ``qmaster`'
  - See ``mechanisms`'

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.22 ec_set_edtime

NAME

      ec_set_edtime() -- set the event delivery interval

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.12 ec_get_edtime.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.23 ec_set_flush

NAME

      ec_set_flush() -- set flushing information for an event

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_set_flush(ev_event event, int flush)

FUNCTION

      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.

INPUTS

      ev_event event - id of the event to configure
      int flush      - the number of seconds between creation of
                       the event and flushing of the messages.

RESULT

      int - 1 on success, else 0

SEE ALSO
  - 1.5 -Flushing.
  - 1.8.13 ec_get_flush.
  - 1.8.27 ec_unset_flush.
  - 1.8.26 ec_subscribe_flush.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.24 ec_subscribe

NAME

      ec_subscribe() -- Subscribe an event

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_subscribe(ev_event event)

FUNCTION

      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.

INPUTS

      ev_event event - the event number

RESULT

      int - 1 on success, else 0

SEE ALSO
  - 1.4 -Events.
  - 1.8.25 ec_subscribe_all.
  - 1.8.28 ec_unsubscribe.
  - 1.8.29 ec_unsubscribe_all.
  - 1.8.4 ec_commit.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.25 ec_subscribe_all

NAME

      ec_subscribe_all() -- subscribe all events

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.24 ec_subscribe.
  - 1.8.28 ec_unsubscribe.
  - 1.8.29 ec_unsubscribe_all.
  - 1.8.4 ec_commit.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.26 ec_subscribe_flush

NAME

      ec_subscribe_flush() -- subscribe an event and set flushing

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_subscribe_flush(ev_event event, int flush)

FUNCTION

      Subscribes and event and configures flushing for this event.

INPUTS

      ev_event event - id of the event to subscribe and flush
      int flush      - number of seconds between event creation
                       and flushing of events

RESULT

      int - 1 on success, else 0

SEE ALSO
  - 1.7 -Subscription.
  - 1.5 -Flushing.
  - 1.8.24 ec_subscribe.
  - 1.8.23 ec_set_flush.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.27 ec_unset_flush

NAME

      ec_unset_flush() -- unset flushing information

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_unset_flush(ev_event event)

FUNCTION

      Switch of flushing of an individual event.

INPUTS

      ev_event event - if of the event to configure

RESULT

      int - 1 on success, else 0

SEE ALSO
  - 1.5 -Flushing.
  - 1.8.23 ec_set_flush.
  - 1.8.13 ec_get_flush.
  - 1.8.26 ec_subscribe_flush.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.28 ec_unsubscribe

NAME

      ec_unsubscribe() -- unsubscribe an event

SYNOPSIS

      #include "sge_event_client.h"

      int
      ec_unsubscribe(ev_event 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

      ev_event 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
  - 1.4 -Events.
  - 1.8.24 ec_subscribe.
  - 1.8.25 ec_subscribe_all.
  - 1.8.29 ec_unsubscribe_all.
  - 1.8.4 ec_commit.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.29 ec_unsubscribe_all

NAME

      ec_unsubscribe_all() -- unsubscribe all events

SYNOPSIS

      #include "sge_event_client.h"

      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
  - 1.8.24 ec_subscribe.
  - 1.8.25 ec_subscribe_all.
  - 1.8.28 ec_unsubscribe.
  - 1.8.4 ec_commit.
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.8.30 get_event_list

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
  - 1.8.8 ec_get.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.9 Server

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.1 --Event_Client_Server

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.

SEE ALSO
  - 1.2 --Event_Client_Interface.
  - 1.9.6 reinit_event_client.
  - 1.9.10 sge_add_event_client.
  - 1.9.18 sge_mod_event_client.
  - 1.9.12 sge_event_client_exit.
  - 1.9.15 sge_gdi_kill_eventclient.
  - 1.9.13 sge_eventclient_subscribed.
  - 1.9.8 sge_ack_event.
  - 1.9.4 ck_4_deliver_events.
  - 1.9.14 sge_flush_events.
  - 1.9.19 sge_next_flush.
  - 1.9.11 sge_add_list_event.
  - 1.9.9 sge_add_event.
  - 1.9.17 sge_get_next_event_number.
  - 1.9.16 sge_gdi_tsm.
  - 1.9.5 eventclient_list_locate.
  - 1.9.7 set_event_client_busy.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.2 -Event_Client_Server_Defines

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).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.3 check_send_new_subscribed_list

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,
                                     ev_event 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
      ev_event event               - the event to check

SEE ALSO
  - 1.9.20 sge_total_update_event.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.4 ck_4_deliver_events

NAME

      ck_4_deliver_events() -- deliver events if necessary

SYNOPSIS

      #include "sge_event_master.h"

      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
  - See ``Eventclient/Server/-Event_Client_Server_Global_Variables`'
  - 1.9.8 sge_ack_event.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.5 eventclient_list_locate

NAME

      eventclient_list_locate() -- search for the scheduler

SYNOPSIS

      #include "sge_event_master.h"

      lListElem *
      eventclient_list_locate(ev_registration_id id)

FUNCTION

      Searches the event client list for an event client with the
      specified id.
      Returns a pointer to the event client object or
      NULL, if no such event client is registered.

INPUTS

      ev_registration_id id - id of the event client to search

RESULT

      lListElem* - event client object or NULL.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.6 reinit_event_client

NAME

      reinit_event_client() -- do a total update for the scheduler

SYNOPSIS

      #include "sge_event_master.h"

      int
      reinit_event_client(ev_registration_id id)

FUNCTION

      Does a total update (send all lists) to the event client specified by id
      and outputs an error message.

INPUTS

      ev_registration_id id - the id of the event client to reinitialize.

RESULT

      int - 0 if reinitialization failed, e.g. because the event client does
            not exits, else 0

SEE ALSO
  - 1.9.21 total_update.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.7 set_event_client_busy

NAME

      set_event_client_busy() -- set the busy state of event clients

SYNOPSIS

      #include "sge_event_master.h"

      void
      set_event_client_busy(lListElem *event_client, int busy)

FUNCTION

      Sets the busy state of one or all event clients.

INPUTS

      lListElem *event_client - the event client to modify - NULL to modify all
      int busy                - busy state - 0 = not busy, 1 = busy

NOTES

      The busy state should better be a boolean if it this datatype was
      available in the cull library.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.8 sge_ack_event

NAME

      sge_ack_event() -- process acknowledge to event delivery

SYNOPSIS

      #include "sge_event_master.h"

      int
      sge_ack_event(lListElem *event_client, ev_event 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.
      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".

INPUTS

      lListElem *event_client - event client sending acknowledge
      ev_event 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
  - 1.9.17 sge_get_next_event_number.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.9 sge_add_event

NAME

      sge_add_event() -- add an object as event

SYNOPSIS

      #include "sge_event_master.h"

      void
      sge_add_event(lListElem *event_client, u_long32 timestamp, ev_event 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 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
      lListElem *element      - the object to deliver as event

NOTES

      Do we need the additional data fields?

SEE ALSO
  - 1.9.11 sge_add_list_event.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.10 sge_add_event_client

NAME

      sge_add_event_client() -- register a new event client

SYNOPSIS

      #include "sge_event_master.h"

      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 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 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

SEE ALSO
  - 1.9.18 sge_mod_event_client.
  - 1.9.15 sge_gdi_kill_eventclient.
  - 1.9.21 total_update.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.11 sge_add_list_event

NAME

      sge_add_list_event() -- add a list as event

SYNOPSIS

      #include "sge_event_master.h"

      void
      sge_add_list_event(lListElem *event_client, u_long32 timestamp,
                         ev_event 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 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
      lList *list             - the list to deliver as event

NOTES

      Do we need the additional data fields?

SEE ALSO
  - 1.9.9 sge_add_event.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.12 sge_event_client_exit

NAME

      sge_event_client_exit() -- event client deregisters

SYNOPSIS

      #include "sge_event_master.h"

      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 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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.13 sge_eventclient_subscribed

NAME

      sge_eventclient_subscribed() -- has event client subscribed an event?

SYNOPSIS

      #include "sge_event_master.h"

      int
      sge_eventclient_subscribed(const lListElem *event_client, ev_event event)

FUNCTION

      Checks if the given event client has a certain event subscribed.

INPUTS

      const lListElem *event_client - event client to check
      ev_event event                - event to check

RESULT

      int - 0 = not subscribed, 1 = subscribed

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.14 sge_flush_events

NAME

      sge_flush_events() -- set the flushing time for events

SYNOPSIS

      #include "sge_event_master.h"

      void
      sge_flush_events(lListElem *event_client, int interval)

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 interval            - time in seconds until next flush

SEE ALSO
  - 1.9.4 ck_4_deliver_events.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.15 sge_gdi_kill_eventclient

NAME

      sge_gdi_kill_eventclient() -- kill an event client

SYNOPSIS

      #include "sge_event_master.h"

      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
  - See ``qconf`'
  - See ``-kec`'

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.16 sge_gdi_tsm

NAME

      sge_gdi_tsm() -- trigger scheduling

SYNOPSIS

      #include "sge_event_master.h"

      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.
      Or it should be possible to trigger any event client.

SEE ALSO
  - See ``qconf`'
  - See ``-tsm`'

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.17 sge_get_next_event_number

NAME

      sge_get_next_event_number() -- next event number for an event client

SYNOPSIS

      #include "sge_event_master.h"

      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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.18 sge_mod_event_client

NAME

      sge_mod_event_client() -- modify event client

SYNOPSIS

      #include "sge_event_master.h"

      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
  - 1.9.3 check_send_new_subscribed_list.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.19 sge_next_flush

NAME

      sge_next_flush() -- when will be the next flush of events?

SYNOPSIS

      #include "sge_event_master.h"

      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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.20 sge_total_update_event

NAME

      sge_total_update_event() -- create a total update event

SYNOPSIS

      static void
      sge_total_update_event(lListElem *event_client, ev_event 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
      ev_event type           - event describing the list to update

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.9.21 total_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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.10 event_text

NAME

      event_text() -- deliver event description

SYNOPSIS

      const char* event_text(const lListElem *event)

FUNCTION

      Deliveres a short description of an event object.

INPUTS

      const lListElem *event - the event to describe

RESULT

      const char* - pointer to the descriptive string.

NOTES

      The result points to a static buffer. Subsequent calls to i
      event_text will overwrite previous results.@end smallexample

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# Function Index

Jump to: | - C E G R S T

| Index Entry | Section
- |  |
| `--EV_Type` | 1.1 --EV_Type
| `--Event_Client` | 1.8.1 --Event_Client
| `--Event_Client_Interface` | 1.2 --Event_Client_Interface
| `--Event_Client_Server` | 1.9.1 --Event_Client_Server
| `-Busy-state` | 1.3 -Busy-state
| `-Event_Client_Global_Variables` | 1.8.2 -Event_Client_Global_Variables
| `-Event_Client_Server_Defines` | 1.9.2 -Event_Client_Server_Defines
| `-Events` | 1.4 -Events
| `-Flushing` | 1.5 -Flushing
| `-ID-numbers` | 1.6 -ID-numbers
| `-Subscription` | 1.7 -Subscription
C |  |
| `check_send_new_subscribed_list` | 1.9.3 check_send_new_subscribed_list
| `ck_4_deliver_events` | 1.9.4 ck_4_deliver_events
| `ck_event_number` | 1.8.3 ck_event_number
E |  |
| `ec_commit` | 1.8.4 ec_commit
| `ec_commit_multi` | 1.8.5 ec_commit_multi
| `ec_config_changed` | 1.8.6 ec_config_changed
| `ec_deregister` | 1.8.7 ec_deregister
| `ec_get` | 1.8.8 ec_get
| `ec_get_busy` | 1.8.9 ec_get_busy
| `ec_get_busy_handling` | 1.8.10 ec_get_busy_handling
| `ec_get_clientdata` | 1.8.11 ec_get_clientdata
| `ec_get_edtime` | 1.8.12 ec_get_edtime
| `ec_get_flush` | 1.8.13 ec_get_flush
| `ec_is_initialized` | 1.8.14 ec_is_initialized
| `ec_mark4registration` | 1.8.15 ec_mark4registration
| `ec_need_new_registration` | 1.8.16 ec_need_new_registration
| `ec_prepare_registration` | 1.8.17 ec_prepare_registration
| `ec_register` | 1.8.18 ec_register
| `ec_set_busy` | 1.8.19 ec_set_busy
| `ec_set_busy_handling` | 1.8.20 ec_set_busy_handling
| `ec_set_clientdata` | 1.8.21 ec_set_clientdata
| `ec_set_edtime` | 1.8.22 ec_set_edtime
| `ec_set_flush` | 1.8.23 ec_set_flush
| `ec_subscribe` | 1.8.24 ec_subscribe
| `ec_subscribe_all` | 1.8.25 ec_subscribe_all
| `ec_subscribe_flush` | 1.8.26 ec_subscribe_flush
| `ec_unset_flush` | 1.8.27 ec_unset_flush
| `ec_unsubscribe` | 1.8.28 ec_unsubscribe
| `ec_unsubscribe_all` | 1.8.29 ec_unsubscribe_all
| `event_text` | 1.10 event_text
| `eventclient_list_locate` | 1.9.5 eventclient_list_locate
G |  |
| `get_event_list` | 1.8.30 get_event_list
R |  |
| `reinit_event_client` | 1.9.6 reinit_event_client
S |  |
| `set_event_client_busy` | 1.9.7 set_event_client_busy
| `sge_ack_event` | 1.9.8 sge_ack_event
| `sge_add_event` | 1.9.9 sge_add_event
| `sge_add_event_client` | 1.9.10 sge_add_event_client
| `sge_add_list_event` | 1.9.11 sge_add_list_event
| `sge_event_client_exit` | 1.9.12 sge_event_client_exit
| `sge_eventclient_subscribed` | 1.9.13 sge_eventclient_subscribed
| `sge_flush_events` | 1.9.14 sge_flush_events
| `sge_gdi_kill_eventclient` | 1.9.15 sge_gdi_kill_eventclient
| `sge_gdi_tsm` | 1.9.16 sge_gdi_tsm
| `sge_get_next_event_number` | 1.9.17 sge_get_next_event_number
| `sge_mod_event_client` | 1.9.18 sge_mod_event_client
| `sge_next_flush` | 1.9.19 sge_next_flush
| `sge_total_update_event` | 1.9.20 sge_total_update_event
T |  |
| `total_update` | 1.9.21 total_update

Jump to: | - C E G R S T

[Top] | [Contents] | [Index] | [ ? ]

# Table of Contents

> 1. Eventclient

> > 1.1 --EV_Type
> > 1.2 --Event_Client_Interface
> > 1.3 -Busy-state
> > 1.4 -Events
> > 1.5 -Flushing
> > 1.6 -ID-numbers
> > 1.7 -Subscription
> > 1.8 Client

> > > 1.8.1 --Event_Client
> > > 1.8.2 -Event_Client_Global_Variables
> > > 1.8.3 ck_event_number
> > > 1.8.4 ec_commit
> > > 1.8.5 ec_commit_multi
> > > 1.8.6 ec_config_changed
> > > 1.8.7 ec_deregister
> > > 1.8.8 ec_get
> > > 1.8.9 ec_get_busy
> > > 1.8.10 ec_get_busy_handling
> > > 1.8.11 ec_get_clientdata
> > > 1.8.12 ec_get_edtime
> > > 1.8.13 ec_get_flush
> > > 1.8.14 ec_is_initialized
> > > 1.8.15 ec_mark4registration
> > > 1.8.16 ec_need_new_registration
> > > 1.8.17 ec_prepare_registration
> > > 1.8.18 ec_register
> > > 1.8.19 ec_set_busy
> > > 1.8.20 ec_set_busy_handling
> > > 1.8.21 ec_set_clientdata
> > > 1.8.22 ec_set_edtime
> > > 1.8.23 ec_set_flush
> > > 1.8.24 ec_subscribe
> > > 1.8.25 ec_subscribe_all
> > > 1.8.26 ec_subscribe_flush
> > > 1.8.27 ec_unset_flush
> > > 1.8.28 ec_unsubscribe
> > > 1.8.29 ec_unsubscribe_all
> > > 1.8.30 get_event_list

> > 1.9 Server

> > > 1.9.1 --Event_Client_Server
> > > 1.9.2 -Event_Client_Server_Defines
> > > 1.9.3 check_send_new_subscribed_list
> > > 1.9.4 ck_4_deliver_events
> > > 1.9.5 eventclient_list_locate
> > > 1.9.6 reinit_event_client
> > > 1.9.7 set_event_client_busy
> > > 1.9.8 sge_ack_event
> > > 1.9.9 sge_add_event
> > > 1.9.10 sge_add_event_client
> > > 1.9.11 sge_add_list_event
> > > 1.9.12 sge_event_client_exit
> > > 1.9.13 sge_eventclient_subscribed
> > > 1.9.14 sge_flush_events
> > > 1.9.15 sge_gdi_kill_eventclient
> > > 1.9.16 sge_gdi_tsm
> > > 1.9.17 sge_get_next_event_number
> > > 1.9.18 sge_mod_event_client
> > > 1.9.19 sge_next_flush
> > > 1.9.20 sge_total_update_event
> > > 1.9.21 total_update

> > 1.10 event_text

> Function Index

[Top] | [Contents] | [Index] | [ ? ]

# Short Table of Contents

> 1. Eventclient
> Function Index

[Top] | [Contents] | [Index] | [ ? ]

# About this document

This document was generated using texi2html

The buttons in the navigation panels have the following meaning:

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 |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

- 1. Section One

- 1.1 Subsection One-One

- ...

- 1.2 Subsection One-Two

- 1.2.1 Subsubsection One-Two-One
- 1.2.2 Subsubsection One-Two-Two
- 1.2.3 Subsubsection One-Two-Three <== Current Position
- 1.2.4 Subsubsection One-Two-Four

- 1.3 Subsection One-Three

- ...

- 1.4 Subsection One-Four

This document was generated by Joachim Gabler on February, 24 2003 using texi2html