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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
.\" Ouroboros man pages CC-BY 2017 - 2024
.\" Dimitri Staessens <dimitri@ouroboros.rocks>
.\" Sander Vrijders <sander@ouroboros.rocks>
.TH FLOW_ALLOC 3 2018-10-05 Ouroboros "Ouroboros Programmer's Manual"
.SH NAME
flow_accept, flow_alloc, flow_dealloc \- allocate and free resources
to support Inter-Process Communication
.SH SYNOPSIS
.B #include <ouroboros/dev.h>
\fBint flow_accept(qosspec_t * \fIqs\fB,
const struct timespec * \fItimeo\fB);
int flow_alloc(const char * \fIdst_name\fB, qosspec_t * \fIqs\fB,
const struct timespec * \fItimeo\fB);
int flow_join(const char * \fIdst_name\fB, qosspec_t * \fIqs\fB, const
struct timespec * \fItimeo\fB);
\fBint flow_dealloc(int \fIfd\fB);\fR
Compile and link with \fI-louroboros-dev\fR.
.SH DESCRIPTION
These calls are used to allocate and free system and network resources
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 \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 flows
this process will accept is configured through the IRMd. For an
explanation on configuring which flows an application should accept,
see \fBirm\fR(8).
The \fBflow_alloc\fR() function requests to allocate system and/or
network resources to support Inter-Process Communication between the
calling application and one or more processes accepting flows for
\fBchar * \fIdst_name\fR, which cannot be NULL. The
\fBflow_alloc\fR() call can specify a certain minimum \fBqosspec_t *
\fIqs\fR that has to be guaranteed by the IPC facility allocating the
resources. This can be NULL if there is no QoS to be guaranteed (best
effort service). If \fIqs\fR is not NULL, the value of \fIqs\fR will
be updated to reflect the actual QoS provided by the IPC facility.
The \fBflow_accept\fR() and \fBflow_alloc\fR() take a \fBconst struct
timespec * \fItimeo\fR to specify a timeout. If \fItimeo\fR is NULL,
the call will block indefinitely or until some error condition occurs.
The \fBflow_join\fR() function allows applications to join a broadcast
flow provided by a broadcast layer. The dst is the layer name.
The \fBflow_dealloc\fR() function will release any resources
associated with the flow. This call may block and keep reliable flows
active until all packets are acknowledged.
A \fBqosspec_t\fR specifies the QoS characteristics of a flow.
The fields are:
.TP
\fBdelay\fR (ms)
Maximum one-way delay.
.TP
\fBbandwidth\fR (bits/s)
Minimum bandwidth.
.TP
\fBavailability\fR
Class of 9s (e.g. 5 = 99.999%).
.TP
\fBloss\fR
Tolerated packet loss; 0 selects reliable delivery.
.TP
\fBber\fR
Tolerated bit error rate (errors per billion bits); 0 enables an
end-to-end integrity check (corrupted packets are dropped).
.TP
\fBservice\fR
Framing / reliability class: \fBSVC_RAW\fR (0) disables FRCT;
\fBSVC_MESSAGE\fR (1) preserves SDU boundaries; \fBSVC_STREAM\fR (2) is
a byte stream with no SDU boundaries. \fBSVC_STREAM\fR requires
\fIloss\fR = 0; otherwise
\fBflow_alloc\fR()/\fBflow_accept\fR() returns \fB-EINVAL\fR.
.TP
\fBmax_gap\fR (ms)
Maximum tolerated inter-packet gap. Packets exceeding the gap
budget are dropped under the real-time cubes.
.TP
\fBtimeout\fR (ms)
Peer-liveness timeout; 0 disables. Only applies when FRCT is
enabled (service > 0).
.PP
The library provides predefined cubes:
.TP
\fBqos_raw\fR
No guarantees, no integrity check.
.TP
\fBqos_raw_safe\fR
Best-effort with end-to-end integrity (ber = 0).
.TP
\fBqos_rt\fR / \fBqos_rt_safe\fR
Real-time messages, optimised for latency over reliability;
\fBqos_rt_safe\fR adds an end-to-end integrity check.
.TP
\fBqos_msg\fR
Reliable, SDU-preserving delivery.
.TP
\fBqos_stream\fR
Reliable byte stream; no SDU boundaries are preserved.
.SH RETURN VALUE
On success, \fBflow_accept\fR() and \fBflow_alloc\fR() calls return a
non-negative integer, referred to as a flow descriptor. On failure, a
negative value indicating the error will be returned.
.SH ERRORS
\fBflow_accept\fR(), \fBflow_alloc\fR() and \fBflow_dealloc\fR() can
return the following errors:
.B -EINVAL
An invalid argument was passed.
.B -EIRMD
Failed to contact an IRMd instance.
\fBflow_accept\fR() and \fBflow_alloc\fR() can also return
.B -EBADF
No more flow desciptors or flow_ids available.
.B -ENOMEM
Not enough system memory resources available to allocate the flow.
.B -ETIMEDOUT
Flow allocation timed out.
.B -ECRYPT
The requested encryption is not supported.
.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
_
\fBflow_accept\fR() & Thread safety & MT-Safe
_
\fBflow_alloc\fR() & Thread safety & MT-Safe
_
\fBflow_join\fR() & Thread safety & MT-Safe
_
\fBflow_dealloc\fR() & Thread safety & MT-Safe
.TE
.SH NOTES
The returned file descriptor is subject to a single-reader and
single-writer discipline \(em at most one thread may call
.BR flow_read ()
(or monitor the fd via
.BR fevent ())
and at most one thread may call
.BR flow_write ()
concurrently. See
.BR flow_read (3),
.BR flow_write (3),
and
.BR fevent (3)
for details.
.PP
.BR flow_dealloc ()
must not be called concurrently with any thread that is inside
.BR flow_read (),
.BR flow_write (),
.BR fevent (),
or any other Ouroboros library call on the same fd; the result is
undefined behaviour. Applications must serialise teardown with
in-flight use, e.g. by signalling worker threads to drop the fd
before calling
.BR flow_dealloc ().
.SH TERMINOLOGY
Please see \fBouroboros-glossary\fR(7).
.SH SEE ALSO
.BR fccntl "(3), " fevent "(3), " flow_read "(3), " flow_write "(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/
|
