watcher: add a centralized an generic facility to monitor file descriptors

2013-07-18 16:00:27 +02:00
parent e5b5a66712
commit 32b2a5e04b
6 changed files with 504 additions and 3 deletions
@@ -0,0 +1,97 @@
+/*
+ * Copyright (C) 2013 Martin Willi
+ * Copyright (C) 2013 revosec AG
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * for more details.
+ */
+
+/**
+ * @defgroup watcher watcher
+ * @{ @ingroup processor
+ */
+
+#ifndef WATCHER_H_
+#define WATCHER_H_
+
+typedef struct watcher_t watcher_t;
+typedef enum watcher_event_t watcher_event_t;
+
+#include <library.h>
+
+/**
+ * Callback function to register for file descriptor events.
+ *
+ * The callback is executed asynchronously using a thread from the pool.
+ * Monitoring of fd is temporarily suspended to avoid additional events while
+ * it is processed asynchronously. To allow concurrent events, one can quickly
+ * process it (using a read/write) and return from the callback. This will
+ * re-enable the event, while the data read can be processed in another
+ * asynchronous job.
+ *
+ * On Linux, even if select() marks an FD as "ready", a subsequent read/write
+ * can block. It is therefore highly recommended to use non-blocking I/O
+ * and handle EAGAIN/EWOULDBLOCK gracefully.
+ *
+ * @param data		user data passed during registration
+ * @param fd		file descriptor the event occured on
+ * @param event		type of event
+ * @return			TRUE to keep watching event, FALSE to unregister fd for event
+ */
+typedef bool (*watcher_cb_t)(void *data, int fd, watcher_event_t event);
+
+/**
+ * What events to watch for a file descriptor.
+ */
+enum watcher_event_t {
+	WATCHER_READ = (1<<0),
+	WATCHER_WRITE = (1<<1),
+	WATCHER_EXCEPT = (1<<2),
+};
+
+/**
+ * Watch multiple file descriptors using select().
+ */
+struct watcher_t {
+
+	/**
+	 * Start watching a new file descriptor.
+	 *
+	 * @param fd		file descriptor to start watching
+	 * @param events	ORed set of events to watch
+	 * @param cb		callback function to invoke on events
+	 * @param data		data to pass to cb()
+	 */
+	void (*add)(watcher_t *this, int fd, watcher_event_t events,
+				watcher_cb_t cb, void *data);
+
+	/**
+	 * Stop watching a previously registered file descriptor.
+	 *
+	 * This call blocks until any active callback for this FD returns.
+	 *
+	 * @param fd		file descriptor to stop watching
+	 */
+	void (*remove)(watcher_t *this, int fd);
+
+	/**
+	 * Destroy a watcher_t.
+	 */
+	void (*destroy)(watcher_t *this);
+};
+
+/**
+ * Create a watcher instance.
+ *
+ * @return		watcher
+ */
+watcher_t *watcher_create();
+
+#endif /** WATCHER_H_ @}*/