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.