API

#
# EMULAB-COPYRIGHT
# Copyright (c) 2000-2002 University of Utah and the Flux Group.
# All rights reserved.
#

* event_register: Register with the testbed event system

      #include <event.h>

      event_handle_t event_register(char *name, int threaded);

  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.

  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.

  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.


* event_unregister: Unregister with the testbed event system

      #include <event.h>

      int event_unregister(event_handle_t handle);

  Unregister with the testbed event system. Returns non-zero if the
  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,
                       event_notification_t notification);

  Send the event notification NOTIFICATION.  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.

  Note that NOTIFICATION is not deallocated by event_notify.  The
  caller is responsible for deallocating the notification when it
  is finished with it.


* event_schedule: Schedule an event notification

      #include <event.h>

      int event_schedule(event_handle_t handle,
                         event_notification_t notification,
                         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.

  Note that NOTIFICATION is not deallocated by event_schedule.
  The caller is responsible for deallocating the notification
  when it is finished with it.


* 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.
  The TYPE parameter specifies the event type. Returns
  a pointer to an event notification structure if the operation
  is successful, 0 otherwise.


* event_notification_free: Free an event notification

      #include <event.h>

      int event_notification_free(event_handle_t handle,
                                  event_notification_t notification);

  Free the event notification NOTIFICATION. Returns non-zero if the
  operation is successful, 0 otherwise.


* event_notification_get_*: Get an attribute from an event notification

      #include <event.h>

      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.

  For _opaque and _string: Writes LENGTH bytes into *BUFFER and
  returns non-zero if the named attribute is found, 0 otherwise.


* event_notification_put_*: Add an attribute to an event notification

      #include <event.h>

      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

      #include <event.h>

      int event_notification_remove(event_handle_t handle,
                                    event_notification_t notification,
                                    char *name);

  Remove the attribute with name NAME from the event notification
  NOTIFICATION.  Returns non-zero if the operation is successful,
  0 otherwise.


* 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,
                    char *host,
                    event_type_t type,
                    void *data);

  where HANDLE is the handle to the event server, NOTIFICATION is the
  event notification, HOST and TYPE are the respective attributes of
  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.

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