man/man3/fduserdata.3.html

Content-type: text/html; charset=UTF-8

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of FDUSERDATA</TITLE>
</HEAD><BODY>
<H1>FDUSERDATA</H1>
Section: Library Functions Manual (3)<BR>Updated: January 2023<BR><A HREF="#index">Index</A>
<A HREF="/#/man/index">Return to Main Contents</A><HR>


<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

<P>

fduserdata_create, fduserdata_destroy, fduserdata_destroy_cb,
fduserdata_new, fduserdata_get, fduserdata_put, fduserdata_del -
associate file descriptors with user defined data
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<P>

#include *fduserdata.h*
<P>

FDUSERDATA *fduserdata_create(int size);
<P>

void fduserdata_destroy(FDUSERDATA *fdtable);
<P>

typedef void (*fduserdata_destr_cb_t)(int fd, void *data, void *arg);

<P>


<P>

void fduserdata_destroy_cb(FDUSERDATA *fdtable, fduserdata_destr_cb_t
callback, void *arg);
<P>

void *fduserdata_new(FDUSERDATA *fdtable, int
fd, type);
<P>

void *fduserdata_get(FDUSERDATA *fdtable, int
fd);
<P>

void fduserdata_put(void *data);
<P>

int fduserdata_del(void *data);
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<P>

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>

fduserdata_create and fduserdata_destroy are the
constructor and destructor of the data structure, respectively.
The data structure has been implemented as a hash table, the argument
size of fduserdata_create is the size of the hash
array.
When size is zero the hash array has its default size (64).
<P>

fduserdata_destroy_cb is an alternative destructor which calls
the function callback for each element still in the data
structure.
<P>

fduserdata_new creates a new element.
It is a macro: type is the type of the user data.
<P>

fduserdata_get search the user data associated to the
fd.
<P>

Both fduserdata_new and fduserdata_get lock the
access to the element, so that fduserdata is thread safe.
fduserdata_put unlocks the element and makes it available for
further requests.
<P>

fduserdata_del can be used instead of fduserdata_put
to delete the element.
<A NAME="lbAE">&nbsp;</A>
<H2>RETURN VALUE</H2>

<P>

fduserdata_create returns the descriptor of the data structure
(NULL in case of error).
<P>

fduserdata_new returns the element of type type just
created (NULL in case of error).
<P>

fduserdata_get returns the element or NULL if no data
corresponds to the file descriptor fd.
<P>

fduserdata_del On success, zero is returned.
On error, -1 is returned.
<P>

On error, errno is set appropriately.
<A NAME="lbAF">&nbsp;</A>
<H2>EXAMPLE</H2>

<P>

fduserdata uses a trivial hash table, the optional arg is the size of
the hash table: default value = 64
<DL COMPACT>
<DT><DD>
<PRE>

  FDUSERDATA table = fduserdata_create(0);

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

</PRE>

</DL>
<P>

create a struct mydata for the file descriptor fd.
<DL COMPACT>
<DT><DD>
<PRE>

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

</PRE>

</DL>
<P>

....
set user defined data (data-*fields)
<DL COMPACT>
<DT><DD>
<PRE>

  fduserdata_put(data);

</PRE>

</DL>
<P>

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.
<DL COMPACT>
<DT><DD>
<PRE>

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

</PRE>

</DL>
<P>

...
read/update user defined data (data-&gt;fields) (use fduserdata_del instead
of fduserdata_put to delete the element)
<DL COMPACT>
<DT><DD>
<PRE>

      fduserdata_put(data);
  }

</PRE>

</DL>
<P>

at the end...
when table is no longer required
<DL COMPACT>
<DT><DD>
<PRE>

  fduserdata_destroy(table);

</PRE>

</DL>
<A NAME="lbAG">&nbsp;</A>
<H2>AUTHOR</H2>

<P>

VirtualSquare.
Project leader: Renzo Davoli.
<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">RETURN VALUE</A><DD>
<DT><A HREF="#lbAF">EXAMPLE</A><DD>
<DT><A HREF="#lbAG">AUTHOR</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 15:22:07 GMT, November 27, 2023
</BODY>
</HTML>