From f6b898da88e06399aedbfec87296602aef5c09c2 Mon Sep 17 00:00:00 2001 From: dimitri staessens Date: Tue, 29 Aug 2017 14:30:35 +0200 Subject: dev: Revise fqueue API and add man pages --- doc/man/CMakeLists.txt | 12 ++++++ doc/man/fevent.3 | 1 + doc/man/flow_alloc.3 | 2 +- doc/man/fqueue.3 | 104 +++++++++++++++++++++++++++++++++++++++++++++ doc/man/fqueue_create.3 | 1 + doc/man/fqueue_destroy.3 | 1 + doc/man/fqueue_next.3 | 1 + doc/man/fset.3 | 107 +++++++++++++++++++++++++++++++++++++++++++++++ doc/man/fset_add.3 | 1 + doc/man/fset_create.3 | 1 + doc/man/fset_del.3 | 1 + doc/man/fset_destroy.3 | 1 + doc/man/fset_has.3 | 1 + doc/man/fset_zero.3 | 1 + 14 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 doc/man/fevent.3 create mode 100644 doc/man/fqueue.3 create mode 100644 doc/man/fqueue_create.3 create mode 100644 doc/man/fqueue_destroy.3 create mode 100644 doc/man/fqueue_next.3 create mode 100644 doc/man/fset.3 create mode 100644 doc/man/fset_add.3 create mode 100644 doc/man/fset_create.3 create mode 100644 doc/man/fset_del.3 create mode 100644 doc/man/fset_destroy.3 create mode 100644 doc/man/fset_has.3 create mode 100644 doc/man/fset_zero.3 (limited to 'doc/man') 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 +.\" Sander Vrijders + +.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 + +\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 +.\" Sander Vrijders + +.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 + +\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 -- cgit v1.2.3