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.