chiark / gitweb /
Add many comments to server/play.c, in advance of possible
[disorder] / lib / event.h
index 32bc1d4..2838c41 100644 (file)
@@ -1,26 +1,28 @@
 /*
  * This file is part of DisOrder.
- * Copyright (C) 2004 Richard Kettlewell
+ * Copyright (C) 2004, 2007 Richard Kettlewell
  *
- * This program is free software; you can redistribute it and/or modify
+ * 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
+ * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
- *
- * 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.
- *
+ * 
+ * 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.
+ * 
  * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
- * USA
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+/** @file lib/event.h
+ * @brief DisOrder event loop
  */
-
 #ifndef EVENT_H
 #define EVENT_H
 
+#include <sys/socket.h>
+
 typedef struct ev_source ev_source;
 
 struct rusage;
@@ -51,7 +53,8 @@ int ev_fd(ev_source *ev,
          ev_fdmode mode,
          int fd,
          ev_fd_callback *callback,
-         void *u);
+         void *u,
+         const char *what);
 /* register a callback on a file descriptor */
 
 int ev_fd_cancel(ev_source *ev,
@@ -69,6 +72,8 @@ int ev_fd_enable(ev_source *ev,
                 int fd);
 /* re-enable callbacks on a file descriptor */
 
+void ev_report(ev_source *ev);
+
 /* timeouts *******************************************************************/
 
 typedef int ev_timeout_callback(ev_source *ev,
@@ -146,7 +151,8 @@ typedef int ev_listen_callback(ev_source *ev,
 int ev_listen(ev_source *ev,
              int fd,
              ev_listen_callback *callback,
-             void *u);
+             void *u,
+             const char *what);
 /* register a socket listener callback.  @bind@ and @listen@ should
  * already have been called. */
 
@@ -158,20 +164,36 @@ int ev_listen_cancel(ev_source *ev,
 
 typedef struct ev_writer ev_writer;
 
+/** @brief Error callback for @ref ev_reader and @ref ev_writer
+ * @param ev Event loop
+ * @param errno_value Errno value (might be 0)
+ * @param u As passed to ev_writer_new() or ev_reader_new()
+ * @return 0 on success, non-0 on error
+ *
+ * This is called for a writer in the following situations:
+ * - on error, with @p errno_value != 0
+ * - when all buffered data has been written, with @p errno_value = 0
+ * - after called ev_writer_cancel(), with @p errno_value = 0
+ *
+ * It is called for a reader only on error, with @p errno_value != 0.
+ */
 typedef int ev_error_callback(ev_source *ev,
-                             int fd,
                              int errno_value,
                              void *u);
-/* called when an error occurs on a writer.  Called with @errno_value@
- * of 0 when finished. */
 
 ev_writer *ev_writer_new(ev_source *ev,
                         int fd,
                         ev_error_callback *callback,
-                        void *u);
+                        void *u,
+                        const char *what);
 /* create a new buffered writer, writing to @fd@.  Calls @error@ if an
  * error occurs. */
 
+int ev_writer_time_bound(ev_writer *ev,
+                        int new_time_bound);
+int ev_writer_space_bound(ev_writer *ev,
+                         int new_space_bound);
+
 int ev_writer_close(ev_writer *w);
 /* close a writer (i.e. promise not to write to it any more) */
 
@@ -188,28 +210,50 @@ struct sink *ev_writer_sink(ev_writer *w) attribute((const));
 
 typedef struct ev_reader ev_reader;
 
+/** @brief Called when data is available to read
+ * @param ev Event loop
+ * @param reader Reader
+ * @param fd File descriptor we read from
+ * @param ptr Pointer to first byte
+ * @param bytes Number of bytes available
+ * @param eof True if EOF has been detected
+ * @param u As passed to ev_reader_new()
+ * @return 0 on succes, non-0 on error
+ *
+ * This callback should call ev_reader_consume() to indicate how many bytes you
+ * actually used.  If you do not call it then it is assumed no bytes were
+ * consumed.
+ *
+ * If having consumed some number of bytes it is not possible to do any further
+ * processing until more data is available then the callback can just return.
+ * Note that this is not allowed if @p eof was set.
+ *
+ * If on the other hand it would be possible to do more processing immediately
+ * with the bytes available, but this is undesirable for some other reason,
+ * then ev_reader_incomplete() should be called.  This will arrange a further
+ * callback in the very near future even if no more bytes are read.
+ */
 typedef int ev_reader_callback(ev_source *ev,
                               ev_reader *reader,
-                              int fd,
                               void *ptr,
                               size_t bytes,
                               int eof,
                               void *u);
-/* Called when data is read or an error occurs.  @ptr@ and @bytes@
- * indicate the amount of data available. @eof@ will be 1 at eof. */
 
 ev_reader *ev_reader_new(ev_source *ev,
                         int fd,
                         ev_reader_callback *callback,
                         ev_error_callback *error_callback,
-                        void *u);
+                        void *u,
+                        const char *what);
 /* register a new reader.  @callback@ will be called whenever data is
  * available. */
 
 void ev_reader_buffer(ev_reader *r, size_t nbytes);
-/* specify a buffer size *case */
+/* specify a buffer size */
 
-void ev_reader_consume(ev_reader *r, size_t nbytes);
+void ev_reader_consume(ev_reader *r
+                      , size_t nbytes);
 /* consume @nbytes@ bytes. */
 
 int ev_reader_cancel(ev_reader *r);
@@ -236,6 +280,8 @@ int ev_reader_enable(ev_reader *r);
  * has in fact already arrived.
  */
 
+int ev_tie(ev_reader *r, ev_writer *w);
+
 #endif /* EVENT_H */
 
 /*
@@ -245,4 +291,3 @@ comment-column:40
 fill-column:79
 End:
 */
-/* arch-tag:8e6f230cabf206361c14897f1e03b536 */