6e158cec2c9a264c29dba3ad0ef635df6a77c88e
[strongswan.git] / src / libstrongswan / processing / watcher.h
1 /*
2 * Copyright (C) 2013 Martin Willi
3 * Copyright (C) 2013 revosec AG
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup watcher watcher
18 * @{ @ingroup processor
19 */
20
21 #ifndef WATCHER_H_
22 #define WATCHER_H_
23
24 typedef struct watcher_t watcher_t;
25 typedef enum watcher_event_t watcher_event_t;
26
27 #include <library.h>
28
29 /**
30 * Callback function to register for file descriptor events.
31 *
32 * The callback is executed asynchronously using a thread from the pool.
33 * Monitoring of fd is temporarily suspended to avoid additional events while
34 * it is processed asynchronously. To allow concurrent events, one can quickly
35 * process it (using a read/write) and return from the callback. This will
36 * re-enable the event, while the data read can be processed in another
37 * asynchronous job.
38 *
39 * On Linux, even if select() marks an FD as "ready", a subsequent read/write
40 * can block. It is therefore highly recommended to use non-blocking I/O
41 * and handle EAGAIN/EWOULDBLOCK gracefully.
42 *
43 * @param data user data passed during registration
44 * @param fd file descriptor the event occurred on
45 * @param event type of event
46 * @return TRUE to keep watching event, FALSE to unregister fd for event
47 */
48 typedef bool (*watcher_cb_t)(void *data, int fd, watcher_event_t event);
49
50 /**
51 * What events to watch for a file descriptor.
52 */
53 enum watcher_event_t {
54 WATCHER_READ = (1<<0),
55 WATCHER_WRITE = (1<<1),
56 WATCHER_EXCEPT = (1<<2),
57 };
58
59 /**
60 * Watch multiple file descriptors using select().
61 */
62 struct watcher_t {
63
64 /**
65 * Start watching a new file descriptor.
66 *
67 * Multiple callbacks can be registered for the same file descriptor, and
68 * all of them get notified. Such callbacks are executed concurrently.
69 *
70 * @param fd file descriptor to start watching
71 * @param events ORed set of events to watch
72 * @param cb callback function to invoke on events
73 * @param data data to pass to cb()
74 */
75 void (*add)(watcher_t *this, int fd, watcher_event_t events,
76 watcher_cb_t cb, void *data);
77
78 /**
79 * Stop watching a previously registered file descriptor.
80 *
81 * This call blocks until any active callback for this FD returns. All
82 * callbacks registered for that FD get unregistered.
83 *
84 * @param fd file descriptor to stop watching
85 */
86 void (*remove)(watcher_t *this, int fd);
87
88 /**
89 * Destroy a watcher_t.
90 */
91 void (*destroy)(watcher_t *this);
92 };
93
94 /**
95 * Create a watcher instance.
96 *
97 * @return watcher
98 */
99 watcher_t *watcher_create();
100
101 #endif /** WATCHER_H_ @}*/