NAME

       fduserdata_create,    fduserdata_destroy,    fduserdata_destroy_cb,    fduserdata_new,    fduserdata_get,
       fduserdata_put, fduserdata_del - associate file descriptors with user defined data

SYNOPSIS

       #include <fduserdata.h>

       FDUSERDATA *fduserdata_create(int size);

       void fduserdata_destroy(FDUSERDATA *fdtable);

       typedef void (*fduserdata_destr_cb_t)(int fd, void *data, void *arg);
       void fduserdata_destroy_cb(FDUSERDATA *fdtable, fduserdata_destr_cb_t callback, void *arg);

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

       void *fduserdata_get(FDUSERDATA *fdtable, int fd);

       void fduserdata_put(void *data);

       int fduserdata_del(void *data);

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.

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

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

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

       fduserdata_get search the user data associated to the fd.

       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.

       fduserdata_del can be used instead of fduserdata_put to delete the element.

RETURN VALUE

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

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

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

       fduserdata_del On success, zero is returned. On error, -1 is returned.

       On error, errno is set appropriately.

EXAMPLE

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

AUTHOR

       VirtualSquare. Project leader: Renzo Davoli.

VirtualSquare                                     November 2019                                    FDUSERDATA(3)