.\" Ouroboros man pages (C) 2017
.\" Dimitri Staessens <dimitri.staessens@ugent.be>
.\" Sander Vrijders <sander.vrijders@ugent.be>

.TH FLOW_ALLOC 3 2017-04-10 GNU "Ouroboros Programmer's Manual"

.SH NAME

flow_accept, flow_alloc, flow_dealloc \- allocate and free resources
to support Inter-Process Communication between application process
instances

.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);

\fBint flow_dealloc(int \fIfd\fB);\fR

Compile and link with \fI-louroboros\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 \fB flow_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 application will accept is configured outside of the
program. 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 application process instances
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_dealloc\fR() function will release any resources
associated with the flow.

A \fBqosspec_t\fR specifies the following QoS characteristics of a
flow:

TODO: specify a qosspec_t

.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 port_ids available.

.B -ENOMEM
Not enough system memory resources available to allocate the flow.

.B -ETIMEDOUT
Flow allocation timed out.

.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_dealloc\fR() & Thread safety & MT-Safe
.TE

.SH SEE ALSO

.BR ouroboros_init "(3), " ouroboros_fini "(3), " \
flow_read "(3), " flow_write (3)

.SH COLOPHON
This page is part of the Ouroboros project, found at
https://bitbucket.org/ouroboros-rina/ouroboros