git.gag.com Git - debian/amanda/blob - common-src/event.h

   1 /*
   2  * Amanda, The Advanced Maryland Automatic Network Disk Archiver
   3  * Copyright (c) 1999 University of Maryland at College Park
   4  * All Rights Reserved.
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of U.M. not be used in advertising or
  11  * publicity pertaining to distribution of the software without specific,
  12  * written prior permission.  U.M. makes no representations about the
  13  * suitability of this software for any purpose.  It is provided "as is"
  14  * without express or implied warranty.
  15  *
  16  * U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
  18  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  19  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  20  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  21  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22  *
  23  * Authors: the Amanda Development Team.  Its members are listed in a
  24  * file named AUTHORS, in the root directory of this distribution.
  25  */
  26 /*
  27  * $Id: event.h,v 1.9 2006/06/16 10:55:05 martinea Exp $
  28  */
  29 #ifndef EVENT_H
  30 #define EVENT_H
  31
  32 /*
  33  * These functions define a generic event interface.  One can register a
  34  * function vector and the type of events to act on, and the event handler
  35  * will dispatch as necessary.
  36  */
  37
  38 /*
  39  * An opaque handle returned by the registry functions that can be
  40  * used to unregister an event in the future.
  41  */
  42 struct event_handle;
  43 typedef struct event_handle event_handle_t;
  44
  45 /*
  46  * The 'id' of the event.  The meaning of this depends on the type of
  47  * event we are registering -- see event_register.  The name 'id' is
  48  * historical: it is quite possible to have many outstanding events with
  49  * the same ID (same timeout or same file descriptor).
  50  *
  51  * Event id's are supplied by the caller, and in some cases are cast from
  52  * pointers, so this value must be wide enough to hold a pointer without
  53  * truncation.
  54  */
  55 typedef intmax_t event_id_t;
  56
  57 /*
  58  * The types of events we can register.
  59  */
  60 typedef enum {
  61     EV_READFD,                  /* file descriptor is ready for reading */
  62     EV_WRITEFD,                 /* file descriptor is ready for writing */
  63     EV_TIME,                    /* n seconds have elapsed */
  64     EV_WAIT,                    /* event_wakeup() was called with this id */
  65 } event_type_t;
  66
  67 /*
  68  * The function signature for functions that get called when an event
  69  * fires.
  70  */
  71 typedef void (*event_fn_t)(void *);
  72
  73 /*
  74  * Register an event handler.
  75  *
  76  * For readfd and writefd events, the first arg is the file descriptor.
  77  * There can be multiple callers firing on the same file descriptor.
  78  *
  79  * For signal events, the first arg is the signal number as defined in
  80  * <signal.h>.  There can only be one signal handler. (do we need more?)
  81  *
  82  * For time events, the first arg is the interval in seconds between
  83  * pulses.  There can be multiple time events, of course.  Don't
  84  * count on the time events being too accurate.  They depend on the
  85  * caller calling event_loop() often enough.
  86  */
  87 event_handle_t *event_register(event_id_t, event_type_t, event_fn_t, void *);
  88
  89 /*
  90  * Release an event handler.
  91  */
  92 void event_release(event_handle_t *);
  93
  94 /*
  95  * Wake up all EV_WAIT events waiting on a specific id.  This happens immediately,
  96  * not in the next iteration of the event loop.  If callbacks made during the wakeup
  97  * register a new event with the same ID, that new event will *not* be awakened.
  98  */
  99 int event_wakeup(event_id_t);
 100
 101 /*
 102  * Call event_loop, returning when one of the following conditions is
 103  * true:
 104  *  evt is EV_WAIT, and it is released; or
 105  *  evt is EV_READFD, EV_WRITEFD, or EV_TIME, and it is fired.
 106  */
 107 void event_wait(event_handle_t *evt);
 108
 109 /*
 110  * Process events.  If the argument is nonzero, then the loop does
 111  * not block.
 112  */
 113 void event_loop(int nonblock);
 114
 115 /*
 116  * Get the default GMainLoop object.  Applications which use the Glib
 117  * main loop directly should use this object for calls to e.g.,
 118  * g_main_loop_run(loop).
 119  */
 120 GMainLoop *default_main_loop(void);
 121
 122 /*
 123  * Utility GSources
 124  */
 125
 126 /* Create a GSource that will callback when the given file descriptor is in
 127  * any of the given conditions.  The callback is a simple GSourceFunc.
 128  *
 129  * @param fd: the file descriptr
 130  * @param events: the conditions (GIOCondition flags)
 131  * @return: GSource object
 132  */
 133 GSource * new_fdsource(gint fd, GIOCondition events);
 134
 135 /* Create a GSource that will callback when the given child dies.  The callback
 136  * should match ChildWatchFunc.  Once the callback is made, it will not be called
 137  * again by this source.
 138  *
 139  * Note: This is provided by glib in later versions, but not in version 2.2.0.
 140  * This function and callback is modeled on g_child_watch_source_new.
 141  *
 142  * @param pid: the process ID @return: GSource object
 143  */
 144 typedef void (*ChildWatchFunc)(pid_t pid, gint status, gpointer data);
 145 GSource * new_child_watch_source(pid_t pid);
 146
 147 #endif  /* EVENT_H */