Merged in dstaesse/ouroboros/be-fqueue (pull request #574)

dev: Revise fqueue API and add man pages

14 files changed, 234 insertions, 1 deletions

diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt
index eadd385e..280252ed 100644
--- a/doc/man/CMakeLists.txt
+++ b/doc/man/CMakeLists.txt
@@ -7,6 +7,18 @@ set(MAN_NAMES
   flow_dealloc.3
   flow_read.3
   flow_write.3
+  fqueue.3
+  fqueue_create.3
+  fqueue_destroy.3
+  fqueue_next.3
+  fevent.3
+  fset.3
+  fset_create.3
+  fset_destroy.3
+  fset_zero.3
+  fset_add.3
+  fset_del.3
+  fset_has.3
   )
 
 macro(INSTALL_MAN __mans)
diff --git a/doc/man/fevent.3 b/doc/man/fevent.3
new file mode 100644
index 00000000..0e1f5f07
--- /dev/null
+++ b/doc/man/fevent.3
@@ -0,0 +1 @@
+.so fqueue.3
diff --git a/doc/man/flow_alloc.3 b/doc/man/flow_alloc.3
index dd0fe7ea..662c46ec 100644
--- a/doc/man/flow_alloc.3
+++ b/doc/man/flow_alloc.3
@@ -31,7 +31,7 @@ to support Inter-Process Communication (IPC). Such a collection of
 allocated system and network resources is referred to as a flow. A
 flow has a certain Quality of Service (QoS) associated with it.
 
-The \fB flow_accept\fR() function blocks the calling thread waiting
+The \fBflow_accept\fR() function blocks the calling thread waiting
 for an incoming request to allocate a flow. If \fBqosspec_t * \fIqs\fR
 is not NULL, the value of \fIqs\fR will be updated to reflect the
 actual QoS provided by the IPC facility for the accepted flow. Which
diff --git a/doc/man/fqueue.3 b/doc/man/fqueue.3
new file mode 100644
index 00000000..611d54c7
--- /dev/null
+++ b/doc/man/fqueue.3
@@ -0,0 +1,104 @@
+.\" Ouroboros man pages (C) 2017
+.\" Dimitri Staessens <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.TH FQUEUE 3 2017-08-29 GNU "Ouroboros Programmer's Manual"
+
+.SH NAME
+
+fqueue_create, fqueue_destroy, fqueue_next, fevent \- I/O multiplexing
+on flows
+
+.SH SYNOPSIS
+
+.B #include <ouroboros/fqueue.h>
+
+\fBfqueue_t * fqueue_create(void);\fR
+
+\fBvoid fqueue_destroy(fqueue_t * \fIfq\fB);
+
+\fBint fqueue_next(fqueue_t * \fIfq\fB);
+
+\fBint fevent(fset_t * \fIset\fB, fqueue_t * \fIfq\fB,
+const struct timespec * \fItimeo\fB);
+
+Compile and link with \fI-louroboros\fR.
+
+.SH DESCRIPTION
+
+These calls are used to
+
+The \fBfqueue_create\fR() function creates an fqueue_t structure which
+is an event queue that stores events that occured within a certain
+\fBfset_t\fR.
+
+The \fBfqueue_destroy\fR() function frees any resources associated with
+an \fBfqueue_t\fR \fIfq\fR.
+
+The \fBfqueue_next\fR() function retrieves the next event (a \fIflow
+descriptor\fR) that is ready within the event queue \fIfq\fR.
+
+The \fBfevent\fR() function retrieves all events that occured on any
+\fIflow descriptor\fR within \fIset\fR and returns them in the event
+queue \fBfq\fR. If a \fBstruct timespec *\fI timeo\fR can be provided,
+it will return either with new events or when \fItimeo\fR has expired.
+If \fItimeo\fR is NULL, the call will block indefinitely until an
+event occurs.
+
+.SH RETURN VALUE
+
+On success, \fBfqueue_create\fR() returns a pointer to an
+\fBfqueue_t\fR.
+
+\fBfqueue_destroy\fR() has no return value.
+
+On success, \fBfevent\fR() returns the number of events that occured in \fIset\fR.
+
+.SH ERRORS
+
+\fBfqueue_create\fR() returns NULL when insufficient resources
+were available to create the \fBfqueue_t\fR.
+
+\fBfqueue_next\fR() and \fBfevent\fR() can return
+
+.B -EINVAL
+An invalid argument was passed (\fIfq\fR or \fIset\fR was \fINULL\fR).
+
+In addition, \fBfqueue_next\fR() can return
+
+.B -EPERM
+No more fds available in \fIfq\fR.
+
+and \fBfevent\fR() can return
+
+.B -ETIMEDOUT
+the interval set int \fItimeo\tR expired before any event in \fIset\fR
+occured.
+
+.SH ATTRIBUTES
+
+For an explanation of the terms used in this section, see \fBattributes\fR(7).
+
+.TS
+box, tab(&);
+LB|LB|LB
+L|L|L.
+Interface & Attribute & Value
+_
+\fBfqueue_create\fR() & Thread safety & MT-Safe
+_
+\fBfqueue_destroy\fR() & Thread safety & MT-Safe
+_
+\fBfqueue_next\fR() & Thread safety & MT-Safe
+_
+\fBfevent\fR() & Thread safety & MT-Safe
+.TE
+
+.SH SEE ALSO
+
+.BR fset_create "(3), " fset_destroy "(3), " \
+fset_add "(3), " fset_del "(3), " fset_has "(3), " fset_zero (3)
+
+.SH COLOPHON
+This page is part of the Ouroboros project, found at
+https://bitbucket.org/ouroboros-rina/ouroboros
diff --git a/doc/man/fqueue_create.3 b/doc/man/fqueue_create.3
new file mode 100644
index 00000000..0e1f5f07
--- /dev/null
+++ b/doc/man/fqueue_create.3
@@ -0,0 +1 @@
+.so fqueue.3
diff --git a/doc/man/fqueue_destroy.3 b/doc/man/fqueue_destroy.3
new file mode 100644
index 00000000..0e1f5f07
--- /dev/null
+++ b/doc/man/fqueue_destroy.3
@@ -0,0 +1 @@
+.so fqueue.3
diff --git a/doc/man/fqueue_next.3 b/doc/man/fqueue_next.3
new file mode 100644
index 00000000..0e1f5f07
--- /dev/null
+++ b/doc/man/fqueue_next.3
@@ -0,0 +1 @@
+.so fqueue.3
diff --git a/doc/man/fset.3 b/doc/man/fset.3
new file mode 100644
index 00000000..b4f3a1b0
--- /dev/null
+++ b/doc/man/fset.3
@@ -0,0 +1,107 @@
+.\" Ouroboros man pages (C) 2017
+.\" Dimitri Staessens <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.TH FSET 3 2017-04-10 GNU "Ouroboros Programmer's Manual"
+
+.SH NAME
+
+fset_create, fset_destroy, fset_zero, fset_add, fset_del, fset_has \-
+manipulation of a set of flow descriptors
+
+.SH SYNOPSIS
+
+.B #include <ouroboros/fqueue.h>
+
+\fBfset_t * fset_create(void);
+
+\fBvoid fset_destroy(fset_t * \fIset\fB);
+
+\fBvoid fset_zero(fset_t * \fIset\fB);
+
+\fBint fset_add(fset_t * \fIset\fB, int \fIfd\fB);
+
+\fBint fset_del(fset_t * \fIset\fB, int \fIfd\fB);
+
+\fBbool fset_has(fset_t * \fIset\fB, int \fIfd\fB);
+
+Compile and link with \fI-louroboros\fR.
+
+.SH DESCRIPTION
+
+These calls are used to manage a set of \fIflow descriptors\fR.
+
+The \fBfset_create\fR() function creates and fset_t struct which holds
+a set of flow descriptors.
+
+The \fBfset_destroy\fR() function frees any resources associated with
+an \fBfset_t \fIset\fR.
+
+The \fBset_zero\fR() function removes all flow descriptors from an
+\fBfset_t \fIset\fR.
+
+The \fBset_add\fR() function adds a flow descriptor \fIfd\fR to the
+\fBfset_t \fIset\fR. A flow descriptor can be in at most one fset at a
+time.
+
+The \fBfset_del\fR() function removes a flow descriptor \fIfd\fR from
+the \fBfset_t \fIset\fR. \fBfset_del\fR() ignores invalid input.
+
+The \fBfset_has\fR() function checks whether a flow descriptor \fIfd\fR is
+an element of the \fBfset_t \fIset\fR.
+
+.SH RETURN VALUE
+
+On success, \fBfset_create\fR() returns a pointer to an \fBfset_t\fB.
+
+\fBfset_destroy\fR(), \fBset_zero\fR() and \fBfset_del\fR() have no return value.
+
+\fBfset_add\fR() returns 0 on success or an error code.
+
+\fBfset_has\fR() returns true when \fIfd\fR is in the set, false if it
+is not or on invalid input.
+
+.SH ERRORS
+
+\fBfset_create\fR() returns NULL when insufficient resources
+were available to create the \fBfset_t\fR.
+
+\fBfset_add\fR() can return the following errors:
+
+.B -EINVAL
+An invalid argument was passed (\fIset\fR was NULL or \fIfd\fR was
+invalid).
+
+.B -EPERM
+The passed flow descriptor \fIfd\fR was already in another \fBfset_t\fR.
+
+.SH ATTRIBUTES
+
+For an explanation of the terms used in this section, see \fBattributes\fR(7).
+
+.TS
+box, tab(&);
+LB|LB|LB
+L|L|L.
+Interface & Attribute & Value
+_
+\fBfset_create\fR() & Thread safety & MT-Safe
+_
+\fBfset_destroy\fR() & Thread safety & MT-Safe
+_
+\fBfset_zero\fR() & Thread safety & MT-Safe
+_
+\fBfset_add\fR() & Thread safety & MT-Safe
+_
+\fBfset_del\fR() & Thread safety & MT-Safe
+_
+\fBfset_has\fR() & Thread safety & MT-Safe
+.TE
+
+.SH SEE ALSO
+
+.BR fqueue "(3), " fevent (3)
+
+.SH COLOPHON
+This page is part of the Ouroboros project, found at
+https://bitbucket.org/ouroboros-rina/ouroboros
diff --git a/doc/man/fset_add.3 b/doc/man/fset_add.3
new file mode 100644
index 00000000..9fe22cd3
--- /dev/null
+++ b/doc/man/fset_add.3
@@ -0,0 +1 @@
+.so fset.3
diff --git a/doc/man/fset_create.3 b/doc/man/fset_create.3
new file mode 100644
index 00000000..9fe22cd3
--- /dev/null
+++ b/doc/man/fset_create.3
@@ -0,0 +1 @@
+.so fset.3
diff --git a/doc/man/fset_del.3 b/doc/man/fset_del.3
new file mode 100644
index 00000000..9fe22cd3
--- /dev/null
+++ b/doc/man/fset_del.3
@@ -0,0 +1 @@
+.so fset.3
diff --git a/doc/man/fset_destroy.3 b/doc/man/fset_destroy.3
new file mode 100644
index 00000000..9fe22cd3
--- /dev/null
+++ b/doc/man/fset_destroy.3
@@ -0,0 +1 @@
+.so fset.3
diff --git a/doc/man/fset_has.3 b/doc/man/fset_has.3
new file mode 100644
index 00000000..9fe22cd3
--- /dev/null
+++ b/doc/man/fset_has.3
@@ -0,0 +1 @@
+.so fset.3
diff --git a/doc/man/fset_zero.3 b/doc/man/fset_zero.3
new file mode 100644
index 00000000..9fe22cd3
--- /dev/null
+++ b/doc/man/fset_zero.3
@@ -0,0 +1 @@
+.so fset.3