1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
.\" Ouroboros man pages CC-BY 2017 - 2020
.\" Dimitri Staessens <dimitri.staessens@ugent.be>
.\" Sander Vrijders <sander.vrijders@ugent.be>
.TH FQUEUE 3 2017-08-29 Ouroboros "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 fqueue_type(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-dev\fR.
.SH DESCRIPTION
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 \fBfqueue_type\fR() function retrieves the type for the current
event on the fd that was returned by \fBfqueue_next\fR(). Event types
are:
.RS 4
FLOW_PKT: A new packet arrived on this flow and is ready for reading.
FLOW_UP: The flow is now marked UP and ready for read/write.
FLOW_DOWN: The flow is now marked DOWN and cannot be written to.
FLOW_ALLOC: A pending flow is now allocated.
FLOW_DEALLOC: The flow is deallocated by the other (N+1 or N-1)
process.
.RE
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.
On success, \fBfqueue_next\fR() returns the next file descriptor for
which an event occurred.
On success, \fBfqueue_type\fR() returns the event type for the last
event returned by \fBfqueue_next\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() or \fBqueue_type\fR() can return
.B -EPERM
No more fds available or no current event 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 TERMINOLOGY
Please see \fBouroboros-glossary\fR(7).
.SH SEE ALSO
.BR fccntl "(3), " flow_alloc "(3), " flow_read "(3), " fqueue "(3), " \
fset "(3), " ouroboros (8)
.SH COLOPHON
This page is part of the Ouroboros project, found at
http://ouroboros.rocks
These man pages are licensed under the Creative Commons Attribution
4.0 International License. To view a copy of this license, visit
http://creativecommons.org/licenses/by/4.0/
|
