OpenDNSSEC-signer  2.1.4
netio.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2001-2011, NLnet Labs. All rights reserved.
3  *
4  * See LICENSE for the license.
5  *
6  *
7  * The netio module implements event based I/O handling using
8  * pselect(2). Multiple event handlers can wait for a certain event
9  * to occur simultaneously. Each event handler is called when an
10  * event occurs that the event handler has indicated that it is
11  * willing to handle.
12  *
13  * There are four types of events that can be handled:
14  *
15  * NETIO_EVENT_READ: reading will not block.
16  * NETIO_EVENT_WRITE: writing will not block.
17  * NETIO_EVENT_EXCEPT: an exception occurred.
18  * NETIO_EVENT_TIMEOUT: the timeout expired.
19  *
20  * A file descriptor must be specified if the handler is interested in
21  * the first three event types. A timeout must be specified if the
22  * event handler is interested in timeouts. These event types can be
23  * OR'ed together if the handler is willing to handle multiple types
24  * of events.
25  *
26  * The special event type NETIO_EVENT_NONE is available if you wish to
27  * temporarily disable the event handler without removing and adding
28  * the handler to the netio structure.
29  *
30  * The event callbacks are free to modify the netio_handler_type
31  * structure to change the file descriptor, timeout, event types, user
32  * data, or handler functions.
33  *
34  * The main loop of the program must call netio_dispatch to check for
35  * events and dispatch them to the handlers. An additional timeout
36  * can be specified as well as the signal mask to install while
37  * blocked in pselect(2).
38  */
39 
45 #ifndef WIRE_NETIO_H_
46 #define WIRE_NETIO_H_
47 
48 #ifdef HAVE_SYS_SELECT_H
49 #include <sys/select.h>
50 #endif
51 
52 #include <signal.h>
53 
54 #include "config.h"
55 #include "status.h"
56 
57 #ifndef PF_INET
58 #define PF_INET AF_INET
59 #endif
60 #ifndef PF_INET6
61 #define PF_INET6 AF_INET6
62 #endif
63 
64 /*
65  * The type of events a handler is interested in.
66  * These can be OR'ed together to specify multiple event types.
67  *
68  */
75 };
77 
78 typedef struct netio_struct netio_type;
81 
86 typedef void (*netio_event_handler_type)(netio_type *netio,
88 
96 };
97 
103  /*
104  * The file descriptor that should be checked for events. If
105  * the file descriptor is negative only timeout events are
106  * checked for.
107  */
108  int fd;
109  /*
110  * The time when no events should be checked for and the
111  * handler should be called with the NETIO_EVENT_TIMEOUT
112  * event type. Unlike most timeout parameters the time should
113  * be absolute, not relative!
114  */
115  struct timespec* timeout;
116  /*
117  * User data.
118  */
119  void* user_data;
120  /*
121  * The type of events that should be checked for. These types
122  * can be OR'ed together to wait for multiple types of events.
123  */
125  /*
126  * The event handler. The event_types parameter contains the
127  * OR'ed set of event types that actually triggered. The
128  * event handler is allowed to modify this handler object.
129  * The event handler SHOULD NOT block.
130  */
133 };
134 
139 struct netio_struct {
141  /*
142  * Cached value of the current time. The cached value is
143  * cleared at the start of netio_dispatch to calculate the
144  * relative timeouts of the event handlers and after calling
145  * pselect(2) so handlers can use it to calculate a new
146  * absolute timeout.
147  *
148  * Use netio_current_time() to read the current time.
149  */
151  struct timespec cached_current_time;
152  /*
153  * Next handler in the dispatch. Only valid during callbacks.
154  * To make sure that deletes respect the state of the iterator.
155  */
157 };
158 
159 /*
160  * Create a new netio instance.
161  * \param[in] allocator memory allocator
162  * \return netio_type* netio instance
163  *
164  */
165 netio_type* netio_create(void);
166 
167 /*
168  * Add a new handler to netio.
169  * \param[in] netio netio instance
170  * \param[in] handler handler
171  *
172  */
174 
175 /*
176  * Remove the handler from netio.
177  * \param[in] netio netio instance
178  * \param[in] handler handler
179  *
180  */
182 
183 /*
184  * Retrieve the current time (using gettimeofday(2)).
185  * \param[in] netio netio instance
186  * \return const struct timespec* current time
187  *
188  */
189 const struct timespec* netio_current_time(netio_type* netio);
190 
191 /*
192  * Check for events and dispatch them to the handlers.
193  * \param[in] netio netio instance
194  * \param[in] timeout if specified, the maximum time to wait for an
195  * event to arrive.
196  * \param[in] sigmask is passed to the underlying pselect(2) call
197  * \return int the number of non-timeout events dispatched, 0 on timeout,
198  * and -1 on error (with errno set appropriately).
199  *
200  */
201 int netio_dispatch(netio_type* netio, const struct timespec* timeout,
202  const sigset_t* sigmask);
203 
209 void netio_cleanup(netio_type* netio);
210 void netio_cleanup_shallow(netio_type* netio);
211 
218 void timespec_add(struct timespec* left, const struct timespec* right);
219 
220 
221 #ifdef __cplusplus
222 inline netio_events_type
223 operator | (netio_events_type lhs, netio_events_type rhs) {
224  return (netio_events_type) (lhs | rhs);
225 }
226 inline netio_events_type
227 operator |= (netio_events_type &lhs, netio_events_type rhs) {
228  lhs = (netio_events_type) (lhs | rhs);
229  return lhs;
230 }
231 #endif /* __cplusplus */
232 
233 #endif /* WIRE_NETIO_H_ */
void netio_remove_handler(netio_type *netio, netio_handler_type *handler)
Definition: netio.c:72
void netio_cleanup_shallow(netio_type *netio)
Definition: netio.c:355
netio_handler_list_type * handlers
Definition: netio.h:140
netio_handler_type * handler
Definition: netio.h:95
enum netio_events_enum netio_events_type
Definition: netio.h:76
int have_current_time
Definition: netio.h:150
netio_handler_list_type * next
Definition: netio.h:94
const struct timespec * netio_current_time(netio_type *netio)
Definition: netio.c:163
void * user_data
Definition: netio.h:119
void netio_cleanup(netio_type *netio)
Definition: netio.c:336
netio_event_handler_type event_handler
Definition: netio.h:131
void netio_add_handler(netio_type *netio, netio_handler_type *handler)
Definition: netio.c:53
netio_events_enum
Definition: netio.h:69
netio_type * netio_create(void)
Definition: netio.c:39
netio_events_type event_types
Definition: netio.h:124
void timespec_add(struct timespec *left, const struct timespec *right)
Definition: netio.c:131
int netio_dispatch(netio_type *netio, const struct timespec *timeout, const sigset_t *sigmask)
Definition: netio.c:187
struct timespec * timeout
Definition: netio.h:115
void(* netio_event_handler_type)(netio_type *netio, netio_handler_type *handler, netio_events_type event_types)
Definition: netio.h:86
netio_handler_list_type * dispatch_next
Definition: netio.h:156