Rename 'io_read' event hook to 'io'; expose a real tickit_watch_io(3) function

4 files changed, 57 insertions, 1 deletions

diff --git a/man/tickit.7 b/man/tickit.7
index 1b6e18c..e715eb6 100644
--- a/man/tickit.7
+++ b/man/tickit.7
@@ -19,7 +19,7 @@ The toplevel instance manages a tree of \fBTickitWindow\fP instances. The root o
 .PP
 The \fBTickitTerm\fP instance behind the toplevel instance can be obtained by \fBtickit_get_term\fP(3), and is described more in \fBtickit_term\fP(7).
 .PP
-Event handling callback functions can be installed to be called at a later time, by using \fBtickit_watch_timer_after_msec\fP(3), \fBtickit_watch_timer_after_tv\fP(3), or \fBtickit_watch_later\fP(3). The main IO event loop is controlled using \fBtickit_run\fP(3) and \fBtickit_stop\fP(3).
+Event handling callback functions can be installed to be called at a later time, by using \fBtickit_watch_io\fP(3), \fBtickit_watch_timer_after_msec\fP(3), \fBtickit_watch_timer_after_tv\fP(3), or \fBtickit_watch_later\fP(3). The main IO event loop is controlled using \fBtickit_run\fP(3) and \fBtickit_stop\fP(3).
 .PP
 The compile-time and run-time version of the library can be inspected using the macros and functions described in \fBtickit_version\fP(7).
 .SH "TYPICAL STRUCTURE"
diff --git a/man/tickit_watch_io.3 b/man/tickit_watch_io.3
new file mode 100644
index 0000000..0b766e4
--- /dev/null
+++ b/man/tickit_watch_io.3
@@ -0,0 +1,54 @@
+.TH TICKIT_WATCH_IO 3
+.SH NAME
+tickit_watch_io \- invoke a callback when IO is possible
+.SH SYNOPSIS
+.EX
+.B #include <tickit.h>
+.sp
+.BI "typedef enum " TickitIOCondition ;
+.sp
+.B  typedef struct {
+.BI "  int " fd ;
+.BI "  TickitIOCondition " cond ;
+.BI "} " TickitIOWatchInfo ;
+.sp
+.BI "typedef int " TickitCallbackFn "(Tickit *" t ", TickitEventflags " flags ,
+.BI "    void *" info ", void *" user );
+.sp
+.BI "void *tickit_watch_io(Tickit *" t ", int " fd ", TickitIOCondition " cond ,
+.BI "    TickitBindFlags " flags ", TickitCallbackFn *" fn ", void *" user );
+.EE
+.sp
+Link with \fI\-ltickit\fP.
+.SH DESCRIPTION
+\fBtickit_watch_io\fP() registers a callback function to be invoked by the toplevel event loop when IO operations are possible on a given file descriptor. A registered callback will be invoked by a running call to \fBtickit_run\fP(3). The callback function will be invoked whenever the file descriptor is readable, writable, or in a hang-up condition, depending on the requested condition types. The \fIinfo\fP pointer will point to a structure containing the file descriptor and a bitmask of the IO operations currently possible.
+.PP
+The \fIcond\fP argument to \fPtickit_watch_io\fP() should be a bitmask of at least one of the following values:
+.TP
+.B TICKIT_IO_IN
+The file descriptor is ready to perform an input operation, such as reading bytes.
+.TP
+.B TICKIT_IO_OUT
+The file descriptor is ready to perform an output operation, such as writing bytes.
+.TP
+.B TICKIT_IO_HUP
+The file descriptor is in a hang-up condition. Typically this means that a connection such as a socket or pipe has been closed by the peer.
+.PP
+When the callback function is invoked, the \fIinfo\fP struct will contain the file descriptor in the \fIfd\fP field, and the current IO conditions in the \fIcond\fP field. This may be one of the values given above, and in addition may also be one of the following:
+.TP
+.B TICKIT_IO_ERR
+The file descriptor is in an error condition.
+.TP
+.B TICKIT_IO_INVAL
+The file descriptor itself is invalid and does not represent an open file.
+.PP
+If cancelled by \fBtickit_watch_cancel\fP(3) the callback function is invoked with just the \fBTICKIT_EV_UNBIND\fP flag if it had been registered with \fBTICKIT_BIND_UNBIND\fP.
+.SH "RETURN VALUE"
+\fBtickit_watch_io\fP() returns an opaque identifier pointer.
+.SH "SEE ALSO"
+.BR tickit_new_stdio (3),
+.BR tickit_watch_timer_after_msec (3),
+.BR tickit_watch_timer_at_epoch (3),
+.BR tickit_watch_later (3),
+.BR tickit_watch_cancel (3),
+.BR tickit (7)
diff --git a/man/tickit_watch_later.3 b/man/tickit_watch_later.3
index 2476110..334a0b1 100644
--- a/man/tickit_watch_later.3
+++ b/man/tickit_watch_later.3
@@ -23,6 +23,7 @@ If cancelled by \fBtickit_watch_cancel\fP(3) the callback function is invoked wi
 \fBtickit_watch_later\fP() returns an opaque identifier pointer.
 .SH "SEE ALSO"
 .BR tickit_new_stdio (3),
+.BR tickit_watch_io (3),
 .BR tickit_watch_timer_after_msec (3),
 .BR tickit_watch_timer_at_epoch (3),
 .BR tickit_watch_cancel (3),
diff --git a/man/tickit_watch_timer_after_msec.3 b/man/tickit_watch_timer_after_msec.3
index fb468f1..c77496d 100644
--- a/man/tickit_watch_timer_after_msec.3
+++ b/man/tickit_watch_timer_after_msec.3
@@ -25,6 +25,7 @@ If cancelled by \fBtickit_watch_cancel\fP(3) the callback function is invoked wi
 \fBtickit_watch_timer_after_msec\fP() and \fBtickit_watch_timer_after_tv\fP() return an opaque identifier pointer.
 .SH "SEE ALSO"
 .BR tickit_new_stdio (3),
+.BR tickit_watch_io (3),
 .BR tickit_watch_timer_at_epoch (3),
 .BR tickit_watch_later (3),
 .BR tickit_watch_cancel (3),