Man page - fduserdata(3)

Packages contains this manual

Manual

FDUSERDATA

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLE
AUTHOR

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.