API 9.9 KB
Newer Older
Leigh B. Stoller's avatar
Leigh B. Stoller committed
1 2 3 4 5 6
#
# EMULAB-COPYRIGHT
# Copyright (c) 2000-2002 University of Utah and the Flux Group.
# All rights reserved.
#

Ian Murdock's avatar
Ian Murdock committed
7 8 9 10
* event_register: Register with the testbed event system

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
11
      event_handle_t event_register(char *name, int threaded);
Ian Murdock's avatar
Ian Murdock committed
12

13 14 15 16 17
  Register with the testbed event system.  NAME specifies the name of
  the event server.  Returns a pointer to a handle that may be passed
  to other event system routines if the operation is successful, NULL
  otherwise.

Ian Murdock's avatar
Ian Murdock committed
18 19 20 21 22 23 24 25 26
  The THREADED parameter should be set to 1 if the registering
  client is multi-threaded. If THREADED is 1, the event
  library will call routines that are thread-safe, and event
  notifications will be dispatched using background threads (i.e.,
  the client will supply its own event loop). If THREADED is 0, event
  notifications will be dispatched using an event system-provided
  event loop, and the client must call event_main after connecting in
  order to receive notifications.

27 28 29 30 31 32 33 34 35
  Elvin note: NAME is a URL of the form "elvin:/[protocol
  stack]/[endpoint]", where a protocol stack names a transport
  module, a security module, and a marshaling module as a comma
  separated list (e.g., "http,none,xml"), and the endpoint format
  is dependent on the transport module used.  If no protocol
  stack is given, the default stack (tcp, none, xdr) is used.  For the
  testbed's purposes, "elvin://HOSTNAME" should suffice.  If NAME
  is NULL, then Elvin's server discovery protocol will be used to find
  the Elvin server.
Ian Murdock's avatar
Ian Murdock committed
36 37 38 39 40 41 42 43


* event_unregister: Unregister with the testbed event system

      #include <event.h>

      int event_unregister(event_handle_t handle);

Ian Murdock's avatar
Ian Murdock committed
44
  Unregister with the testbed event system. Returns non-zero if the
Ian Murdock's avatar
Ian Murdock committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
  operation is successful, 0 otherwise.


* event_main: Enter the main loop of the event system

      #include <event.h>

      int event_main(event_handle_t handle);

  Enter the main loop of the event system, waiting to receive event
  notifications. Returns non-zero if the operation is successful, 0
  otherwise.


* event_notify: Send an event notification

      #include <event.h>

      int event_notify(event_handle_t handle,
64
                       event_notification_t notification);
Ian Murdock's avatar
Ian Murdock committed
65 66 67

  Send the event notification NOTIFICATION.  NOTIFICATION is
  allocated by event_notification_alloc, and may optionally
Ian Murdock's avatar
Ian Murdock committed
68
  have attributes added to it by event_notification_put_*.
Ian Murdock's avatar
Ian Murdock committed
69 70
  Returns non-zero if the operation is successful, 0 otherwise.

Ian Murdock's avatar
Ian Murdock committed
71 72 73 74
  Note that NOTIFICATION is not deallocated by event_notify.  The
  caller is responsible for deallocating the notification when it
  is finished with it.

Ian Murdock's avatar
Ian Murdock committed
75

Ian Murdock's avatar
Ian Murdock committed
76 77 78 79 80
* event_schedule: Schedule an event notification

      #include <event.h>

      int event_schedule(event_handle_t handle,
81
                         event_notification_t notification,
Ian Murdock's avatar
Ian Murdock committed
82 83 84 85 86 87 88 89 90 91 92 93
                         struct timeval *time);

  Schedule the event notification NOTIFICATION to be sent at time
  TIME. NOTIFICATION is allocated by event_notification_alloc,
  and may optionally have attributes added to it by
  event_notification_put_*. Returns non-zero if the operation
  is successful, 0 otherwise.

  This function essentially operates as a deferred event_notify.
  event_notify sends notifications immediately,
  whereas event_schedule sends notifications at some later time.

Ian Murdock's avatar
Ian Murdock committed
94 95 96 97
  Note that NOTIFICATION is not deallocated by event_schedule.
  The caller is responsible for deallocating the notification
  when it is finished with it.

Ian Murdock's avatar
Ian Murdock committed
98

Ian Murdock's avatar
Ian Murdock committed
99 100 101 102 103 104 105 106 107 108 109
* event_notification_alloc: Allocate an event notification

      #include <event.h>

      event_notification_t event_notification_alloc(event_handle_t handle,
                                                    char *host,
                                                    event_type_t type);

  Allocate an event notification.  The HOST parameter specifies
  the hostname of the node that should receive the notification,
  or EVENT_HOST_ANY if the notification should go to all hosts.
Ian Murdock's avatar
Ian Murdock committed
110 111 112
  The TYPE parameter specifies the event type. Returns
  a pointer to an event notification structure if the operation
  is successful, 0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
113 114 115 116 117 118 119 120 121


* event_notification_free: Free an event notification

      #include <event.h>

      int event_notification_free(event_handle_t handle,
                                  event_notification_t notification);

Ian Murdock's avatar
Ian Murdock committed
122
  Free the event notification NOTIFICATION. Returns non-zero if the
Ian Murdock's avatar
Ian Murdock committed
123 124 125
  operation is successful, 0 otherwise.


Ian Murdock's avatar
Ian Murdock committed
126
* event_notification_get_*: Get an attribute from an event notification
Ian Murdock's avatar
Ian Murdock committed
127 128 129

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
      int event_notification_get_double(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        double *value);
      int event_notification_get_int32(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int32_t *value);
      int event_notification_get_int64(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int64_t *value);
      int event_notification_get_opaque(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        void *buffer,
                                        int length);
      int event_notification_get_string(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        char *buffer,
                                        int length);

  Get the attribute with name NAME from the event notification
  NOTIFICATION.

  For _double, _int32 and _int64: Writes the value of the attribute
  to *VALUE and returns non-zero if the named attribute is found, 0
  otherwise.
Ian Murdock's avatar
Ian Murdock committed
159

Ian Murdock's avatar
Ian Murdock committed
160 161
  For _opaque and _string: Writes LENGTH bytes into *BUFFER and
  returns non-zero if the named attribute is found, 0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
162 163


Ian Murdock's avatar
Ian Murdock committed
164
* event_notification_put_*: Add an attribute to an event notification
Ian Murdock's avatar
Ian Murdock committed
165 166 167

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
      int event_notification_put_double(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        double value);
      int event_notification_put_int32(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int32_t value);
      int event_notification_put_int64(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int64_t value);
      int event_notification_put_opaque(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        void *buffer,
                                        int length);
      int event_notification_put_string(event_handle_t handle,
                                        event_notification_t notification,
                                        char *value);

  Add an attribute with name NAME to the event notification
  NOTIFICATION. For _double, _int32, _int64, and _string: The value
  is specified in VALUE. For _opaque: The value is specified
  in the buffer BUFFER which has length LENGTH. Returns non-zero if
  the operation is successful, 0 otherwise.


* event_notification_attr_remove: Remove an attribute from an event
  notification
Ian Murdock's avatar
Ian Murdock committed
198

Ian Murdock's avatar
Ian Murdock committed
199
      #include <event.h>
Ian Murdock's avatar
Ian Murdock committed
200

Ian Murdock's avatar
Ian Murdock committed
201 202 203
      int event_notification_remove(event_handle_t handle,
                                    event_notification_t notification,
                                    char *name);
Ian Murdock's avatar
Ian Murdock committed
204

Ian Murdock's avatar
Ian Murdock committed
205 206 207
  Remove the attribute with name NAME from the event notification
  NOTIFICATION.  Returns non-zero if the operation is successful,
  0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225


* event_subscribe: Subscribe to an event

      #include <event.h>

      event_subscription_t event_subscribe(event_handle_t handle,
                                           event_notify_callback_t callback,
                                           event_type_t type,
                                           void *data);

  Subscribe to events of type TYPE.  Event notifications that match
  TYPE will be passed to the callback function CALLBACK; DATA is
  an arbitrary pointer that will be passed to the callback function.
  Callback functions are of the form

      void callback(event_handle_t handle,
                    event_notification_t notification,
Ian Murdock's avatar
Ian Murdock committed
226 227
                    char *host,
                    event_type_t type,
Ian Murdock's avatar
Ian Murdock committed
228 229
                    void *data);

Ian Murdock's avatar
Ian Murdock committed
230 231
  where HANDLE is the handle to the event server, NOTIFICATION is the
  event notification, HOST and TYPE are the respective attributes of
Ian Murdock's avatar
Ian Murdock committed
232 233 234
  the event notification, and DATA is the arbitrary pointer passed to
  event_subscribe.  Returns a pointer to an event
  subscription structure if the operation is successful, 0 otherwise.
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257

* event_poll: Poll for new events

      #include <event.h>

      int event_poll(event_handle_t handle);

  Polls for new events. Calls callbacks for all pending events. Does
  not block - simply processes events that are currently queued.

* event_poll_blocking: Poll for new events

      #include <event.h>

      int event_poll_blocking(event_handle_t handle, unsigned int timeout);

  Same as event_poll, but blocks waiting for an event. Times out
  after the given amount of time, or doesn't time out if 0 is given.

  IMPORTANT: elvin uses timeouts internally. So, this function does
  NOT guarantee that when it returns, either an event has been
  recieved or your timeout has passed. This should not be much of
  a problem, but you have been warned!