Annotation of embedaddon/strongswan/src/libstrongswan/processing/watcher.h, revision 1.1
1.1 ! misho 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: typedef enum watcher_state_t watcher_state_t;
! 27:
! 28: #include <library.h>
! 29:
! 30: /**
! 31: * Callback function to register for file descriptor events.
! 32: *
! 33: * The callback is executed asynchronously using a thread from the pool.
! 34: * Monitoring of fd is temporarily suspended to avoid additional events while
! 35: * it is processed asynchronously. To allow concurrent events, one can quickly
! 36: * process it (using a read/write) and return from the callback. This will
! 37: * re-enable the event, while the data read can be processed in another
! 38: * asynchronous job.
! 39: *
! 40: * On Linux, even if select() marks an FD as "ready", a subsequent read/write
! 41: * can block. It is therefore highly recommended to use non-blocking I/O
! 42: * and handle EAGAIN/EWOULDBLOCK gracefully.
! 43: *
! 44: * @param data user data passed during registration
! 45: * @param fd file descriptor the event occurred on
! 46: * @param event type of event
! 47: * @return TRUE to keep watching event, FALSE to unregister fd for event
! 48: */
! 49: typedef bool (*watcher_cb_t)(void *data, int fd, watcher_event_t event);
! 50:
! 51: /**
! 52: * What events to watch for a file descriptor.
! 53: */
! 54: enum watcher_event_t {
! 55: WATCHER_READ = (1<<0),
! 56: WATCHER_WRITE = (1<<1),
! 57: WATCHER_EXCEPT = (1<<2),
! 58: };
! 59:
! 60: /**
! 61: * State the watcher currently is in
! 62: */
! 63: enum watcher_state_t {
! 64: /** no watcher thread running or queued */
! 65: WATCHER_STOPPED = 0,
! 66: /** a job has been queued for watching, but not yet started */
! 67: WATCHER_QUEUED,
! 68: /** a watcher thread is active, dispatching socket events */
! 69: WATCHER_RUNNING,
! 70: };
! 71:
! 72: /**
! 73: * Watch multiple file descriptors using select().
! 74: */
! 75: struct watcher_t {
! 76:
! 77: /**
! 78: * Start watching a new file descriptor.
! 79: *
! 80: * Multiple callbacks can be registered for the same file descriptor, and
! 81: * all of them get notified. Such callbacks are executed concurrently.
! 82: *
! 83: * @param fd file descriptor to start watching
! 84: * @param events ORed set of events to watch
! 85: * @param cb callback function to invoke on events
! 86: * @param data data to pass to cb()
! 87: */
! 88: void (*add)(watcher_t *this, int fd, watcher_event_t events,
! 89: watcher_cb_t cb, void *data);
! 90:
! 91: /**
! 92: * Stop watching a previously registered file descriptor.
! 93: *
! 94: * This call blocks until any active callback for this FD returns. All
! 95: * callbacks registered for that FD get unregistered.
! 96: *
! 97: * @param fd file descriptor to stop watching
! 98: */
! 99: void (*remove)(watcher_t *this, int fd);
! 100:
! 101: /**
! 102: * Get the current watcher state
! 103: *
! 104: * @return currently active watcher state
! 105: */
! 106: watcher_state_t (*get_state)(watcher_t *this);
! 107:
! 108: /**
! 109: * Destroy a watcher_t.
! 110: */
! 111: void (*destroy)(watcher_t *this);
! 112: };
! 113:
! 114: /**
! 115: * Create a watcher instance.
! 116: *
! 117: * @return watcher
! 118: */
! 119: watcher_t *watcher_create();
! 120:
! 121: #endif /** WATCHER_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>