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