API 15.2 KB
Newer Older
Leigh Stoller's avatar
Leigh Stoller committed
1
#
2
# Copyright (c) 2000-2010 University of Utah and the Flux Group.
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
# 
# {{{EMULAB-LICENSE
# 
# This file is part of the Emulab network testbed software.
# 
# This file is free software: you can redistribute it and/or modify it
# under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or (at
# your option) any later version.
# 
# This file is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public
# License for more details.
# 
# You should have received a copy of the GNU Affero General Public License
# along with this file.  If not, see <http://www.gnu.org/licenses/>.
# 
# }}}
Leigh Stoller's avatar
Leigh Stoller committed
22 23
#

24 25 26 27 28 29 30
#
# NB: Any changes to this document should be reflected in the Wiki page:
# http://users.emulab.net/trac/emulab/wiki/EventAPI
#

The Emulab event system API:

Ian Murdock's avatar
Ian Murdock committed
31 32 33 34
* event_register: Register with the testbed event system

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
35
      event_handle_t event_register(char *name, int threaded);
36 37 38 39
      event_handle_t event_register_withkeyfile(char *name, int threaded, char *keyfile);
      event_handle_t event_register_withkeydata(char *name, int threaded, unsigned char *keydata, int len);
      event_handle_t event_register_withkeyfile_withretry(char *name, int threaded, char *keyfile, int retrycount);
      event_handle_t event_register_withkeydata_withretry(char *name, int threaded, unsigned char *keydata, int len, int retrycount);
Ian Murdock's avatar
Ian Murdock committed
40

41 42 43 44 45 46 47 48 49 50 51
  Register with the testbed event system with an optional HMAC key.

  In all forms, NAME specifies the name of the event server and THREADED is
  an indication as to whether the calling application is multi-threaded.
  Returns a pointer to a handle that may be passed to other event system
  routines if the operation is successful, NULL otherwise.

  The syntax of the NAME parameter is inherited from elvin, and is a subset
  of their URI syntax.  It is of the form elvin://<server>:<port> where
  <server> is the IP or DNS name of the server, and PORT is the TCP port
  number to use.
52

Ian Murdock's avatar
Ian Murdock committed
53 54 55 56 57 58 59 60 61
  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.

62 63 64 65
  In the _withretry forms, RETRYCOUNT is the number of attempt to try
  making a connection to the server before failing.  Retries happen
  at a transport-specific interval, in the case of pubsub (the current
  and only supported transport) it is 5 seconds.
Ian Murdock's avatar
Ian Murdock committed
66

67 68 69 70 71
  In the _withkey* forms, the given KEYDATA and LEN or the contents of
  KEYFILE are used as a key for the keyed-hash MAC computation to
  authenticate all events sent or received via the returned handle.
  The HMAC is a SHA1 hash computed using the OpenSSL HMAC_* routines.
  Event HMACs appear as opaque attributes in events.
Ian Murdock's avatar
Ian Murdock committed
72 73 74 75 76 77 78

* 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
79
  Unregister with the testbed event system. Returns non-zero if the
Ian Murdock's avatar
Ian Murdock committed
80 81 82 83 84 85 86 87 88 89
  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
90 91 92 93 94
  notifications. Remains in the main loop until an error occurs or
  event_stop_main is called. Returns non-zero if the operation is
  successful, 0 otherwise.  Should only be called by single-threaded
  programs.

95

96 97 98 99 100
* event_stop_main: Force event_main to return

      #include <event.h>

      event_stop_main(event_handle_t handle)
Ian Murdock's avatar
Ian Murdock committed
101

102 103 104
  Can be called from an event handler or signal handler to force the
  main loop to return, either to check for a completion condition or
  to handle other, non event related processing.
Ian Murdock's avatar
Ian Murdock committed
105

106

Ian Murdock's avatar
Ian Murdock committed
107 108 109 110 111
* event_notify: Send an event notification

      #include <event.h>

      int event_notify(event_handle_t handle,
112
                       event_notification_t notification);
Ian Murdock's avatar
Ian Murdock committed
113 114 115

  Send the event notification NOTIFICATION.  NOTIFICATION is
  allocated by event_notification_alloc, and may optionally
Ian Murdock's avatar
Ian Murdock committed
116
  have attributes added to it by event_notification_put_*.
Ian Murdock's avatar
Ian Murdock committed
117
  Returns non-zero if the operation is successful, 0 otherwise.
118 119
  If HANDLE has an associated hash key, an HMAC is computed and
  added as an attribute before sending.
Ian Murdock's avatar
Ian Murdock committed
120

Ian Murdock's avatar
Ian Murdock committed
121 122 123 124
  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
125

Ian Murdock's avatar
Ian Murdock committed
126 127 128 129 130
* event_schedule: Schedule an event notification

      #include <event.h>

      int event_schedule(event_handle_t handle,
131
                         event_notification_t notification,
Ian Murdock's avatar
Ian Murdock committed
132 133
                         struct timeval *time);

134 135
  Send the indicated notification as a "scheduled" event.
  NOTIFICATION is allocated by event_notification_alloc,
Ian Murdock's avatar
Ian Murdock committed
136 137 138 139 140
  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.
141 142 143 144 145 146 147 148 149 150
  event_notify sends notifications immediately to recipients,
  whereas event_schedule causes notifications to be sent at
  some later time.

  IMPORTANT NOTE: scheduled events are NOT held in the calling process
  for later delivery. Instead, event_schedule adds a SCHEDULER=1 attribute
  to the notification along with attributes for the delivery time, and
  then uses event_notify to immediately send the event. There must be
  an event agent subscribed to SCHEDULER events that implements the
  queuing and later sending of the unadorned notification.
Ian Murdock's avatar
Ian Murdock committed
151

Ian Murdock's avatar
Ian Murdock committed
152 153 154 155
  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
156

Ian Murdock's avatar
Ian Murdock committed
157 158 159 160 161
* event_notification_alloc: Allocate an event notification

      #include <event.h>

      event_notification_t event_notification_alloc(event_handle_t handle,
162 163 164 165 166 167 168 169 170 171 172
						    address_tuple_t tuple);

  Allocate an event notification destined for a particular target.
  The TUPLE parameter describes the target of the notification.
  It contains a set of strings for a standard set of Emulab attributes
  including the Emulab site and host, the project and experiment names,
  the target object type and name, and the event type, group and timeline. 
  All are optional and will be given default "any" values if not specified
  by the caller.

  Returns a pointer to an event notification structure if the operation
Ian Murdock's avatar
Ian Murdock committed
173
  is successful, 0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
174 175 176 177 178 179 180 181 182


* 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
183
  Free the event notification NOTIFICATION. Returns non-zero if the
Ian Murdock's avatar
Ian Murdock committed
184 185 186
  operation is successful, 0 otherwise.


187 188 189 190 191 192 193 194 195 196 197
* event_notification_clone: create a (deep) copy of a notification

      event_notification_t
      event_notification_clone(event_handle_t handle,
			       event_notification_t notification);

  Create an exact copy of NOTIFICATION.
  Returns a pointer to an event notification structure if the operation
  is successful, 0 otherwise.


Ian Murdock's avatar
Ian Murdock committed
198
* event_notification_get_*: Get an attribute from an event notification
Ian Murdock's avatar
Ian Murdock committed
199 200 201

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
      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);
224 225 226 227 228 229
      int event_notification_get_opaque_length(event_handle_t handle,
					     event_notification_t notification,
					     char *name)
      int event_notification_get_string_length(event_handle_t handle,
					     event_notification_t notification,
					     char *name)
Ian Murdock's avatar
Ian Murdock committed
230 231 232 233 234 235 236

  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
237

Ian Murdock's avatar
Ian Murdock committed
238 239
  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
240

241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283
  The _length functions return the length of the named attribute,
  and can be used to size buffers for subsequent get_* calls.


* event_notification_get_<tuple-arg>: extract notification tuple info

      int event_notification_get_site(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_host(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_expt(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_objtype(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_objname(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_eventtype(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_group(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);
      int event_notification_get_timeline(event_handle_t handle,
				      event_notification_t notification,
				      void *buffer,
				      int length);

  Convenience functions for extracting subscription attributes from a
  notification.  Wrappers for event_notification_get_string using the
  specific NAME value.

Ian Murdock's avatar
Ian Murdock committed
284

Ian Murdock's avatar
Ian Murdock committed
285
* event_notification_put_*: Add an attribute to an event notification
Ian Murdock's avatar
Ian Murdock committed
286 287 288

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311
      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
312 313 314
  is specified in VALUE (strings are null-terminated). For _opaque:
  The value is specified in the buffer BUFFER which has length LENGTH.
  Returns non-zero if the operation is successful, 0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
315 316


317
* event_notification_remove: Remove an attribute from an event notification
Ian Murdock's avatar
Ian Murdock committed
318

Ian Murdock's avatar
Ian Murdock committed
319
      #include <event.h>
Ian Murdock's avatar
Ian Murdock committed
320

Ian Murdock's avatar
Ian Murdock committed
321 322 323
      int event_notification_remove(event_handle_t handle,
                                    event_notification_t notification,
                                    char *name);
Ian Murdock's avatar
Ian Murdock committed
324

Ian Murdock's avatar
Ian Murdock committed
325 326 327
  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
328 329 330 331 332 333 334 335


* event_subscribe: Subscribe to an event

      #include <event.h>

      event_subscription_t event_subscribe(event_handle_t handle,
                                           event_notify_callback_t callback,
336
                                           address_tuple_t tuple,
Ian Murdock's avatar
Ian Murdock committed
337 338
                                           void *data);

339 340 341 342 343 344 345 346 347
  Subscribe to events matching the information in TUPLE, arranging for
  CALLBACK to be called with DATA as an argument when an event occurs.
  Returns a pointer to an event subscription structure if the operation
  is successful, 0 otherwise.

  The information in TUPLE is used to create a pubsub boolean expression
  that is a conjunction of all the tuple elements. DATA is an arbitrary
  pointer that will be passed to the callback function. CALLBACK functions
  are of the form:
Ian Murdock's avatar
Ian Murdock committed
348 349 350 351 352

      void callback(event_handle_t handle,
                    event_notification_t notification,
                    void *data);

Ian Murdock's avatar
Ian Murdock committed
353
  where HANDLE is the handle to the event server, NOTIFICATION is the
354 355 356 357 358 359 360 361 362 363 364 365 366 367
  event notification, and DATA is the arbitrary pointer passed to
  event_subscribe. The various event_notification_get_* functions can
  be applied to the notification to extract information.


* event_unsubscribe: Clear a subscription for an event

      #include <event.h>

      int event_unsubscribe(event_handle_t handle, event_subscription_t es);

  Unregister an interest in the specified subscription.  ES is a subscription
  object returned from a previous event_subscribe call.

368 369 370 371 372 373 374 375 376 377

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

378

379 380 381 382 383 384 385
* 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
386
  after the given amount of time (which is in milliseconds), or doesn't time
387
  out if 0 is given.
388 389 390

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