.\" Copyright (C) 2019 VirtualSquare. Project Leader: Renzo Davoli
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License,
.\" as published by the Free Software Foundation, either version 2
.\" of the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
.\" MA 02110-1301 USA.
.\"
.\" generated with Ronn-NG/v0.8.0
.\" http://github.com/apjanke/ronn-ng/tree/0.8.0
.TH "FDUSERDATA" "3" "November 2019" "VirtualSquare"
.SH "NAME"
fduserdata_create, fduserdata_destroy, fduserdata_destroy_cb, fduserdata_new, fduserdata_get, fduserdata_put, fduserdata_del \- associate file descriptors with user defined data
.SH "SYNOPSIS"
\fB#include <fduserdata\.h>\fR
.P
\fBFDUSERDATA *fduserdata_create(int\fR \fIsize\fR\fB);\fR
.P
\fBvoid fduserdata_destroy(FDUSERDATA *\fR\fIfdtable\fR\fB);\fR
.P
\fBtypedef void (*fduserdata_destr_cb_t)(int fd, void *data, void *arg);\fR
.br
\fBvoid fduserdata_destroy_cb(FDUSERDATA *\fR\fIfdtable\fR\fB, fduserdata_destr_cb_t\fR \fIcallback\fR\fB, void *\fR\fIarg\fR\fB);\fR
.P
\fBvoid *fduserdata_new(FDUSERDATA *\fR\fIfdtable\fR\fB, int\fR \fIfd\fR\fB,\fR \fItype\fR\fB);\fR
.P
\fBvoid *fduserdata_get(FDUSERDATA *\fR\fIfdtable\fR\fB, int\fR \fIfd\fR\fB);\fR
.P
\fBvoid fduserdata_put(void *\fR\fIdata\fR\fB);\fR
.P
\fBint fduserdata_del(void *\fR\fIdata\fR\fB);\fR
.SH "DESCRIPTION"
This library permits one to associate file descriptors with user defined data, more precisely it manages a data structure whose searching key is a file descriptor\.
.P
\fBfduserdata_create\fR and \fBfduserdata_destroy\fR are the constructor and destructor of the data structure, respectively\. The data structure has been implemented as a hash table, the argument \fIsize\fR of \fBfduserdata_create\fR is the size of the hash array\. When \fIsize\fR is zero the hash array has its default size (64)\.
.P
\fBfduserdata_destroy_cb\fR is an alternative destructor which calls the function \fIcallback\fR for each element still in the data structure\.
.P
\fBfduserdata_new\fR creates a new element\. It is a macro: \fItype\fR is the type of the user data\.
.P
\fBfduserdata_get\fR search the user data associated to the \fIfd\fR\.
.P
Both \fBfduserdata_new\fR and \fBfduserdata_get\fR lock the access to the element, so that fduserdata is thread safe\. \fBfduserdata_put\fR unlocks the element and makes it available for further requests\.
.P
\fBfduserdata_del\fR can be used instead of \fBfduserdata_put\fR to delete the element\.
.SH "RETURN VALUE"
\fBfduserdata_create\fR returns the descriptor of the data structure (NULL in case of error)\.
.P
\fBfduserdata_new\fR returns the element of type \fItype\fR just created (NULL in case of error)\.
.P
\fBfduserdata_get\fR returns the element or NULL if no data corresponds to the file descriptor \fIfd\fR\.
.P
\fBfduserdata_del\fR On success, zero is returned\. On error, \-1 is returned\.
.P
On error, \fIerrno\fR is set appropriately\.
.SH "EXAMPLE"
.nf
fduserdata uses a trivial hash table, the optional arg is the
size of the hash table: default value = 64

    FDUSERDATA table = fduserdata_create(0);

    struct mydata {
    // fd data fields \|\.\|\.\|\.
    };

create a struct mydata for the file descriptor fd\.

    struct mydata *data = fduserdata_new(table, fd, struct mydata);

\|\.\|\.\|\.\. set user defined data (data\->fields)

    fduserdata_put(data);

search for data
there is mutual exclusion between new/put, get/put (or new/del, get/del)
so do not insert time consuming or blocking ops\.

    struct mydata *fddata = fduserdata_get(table, fd);
    if (fddata) {

\|\.\|\.\|\. read/update user defined data (data\->fields)
(use fduserdata_del instead of fduserdata_put to delete the element)

          fduserdata_put(data);
    }

at the end\|\.\|\.\|\. when table is no longer required

    fduserdata_destroy(table);
.fi
.SH "AUTHOR"
VirtualSquare\. Project leader: Renzo Davoli\.