TABLE OF CONTENTS

libram/_libram_cb_add [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

_libram_cb_add - add function to callback list

SYNOPSIS

static struct _ram_cb_node *_libram_cb_add(ram_cb h,
                        long id,
                        void (*cb)(void*, char *msg, void*),
                        void *arg, char *msg)

DESCRIPTION

_libram_cb_add(3) allocates a _ram_cb_node and initializes this node with the given parameter.

ARGUMENTS

RETURN

SEE ALSO

libram_cb_register(3), _ram_cb_node(3), ram_cb(3), libram-cb(3), libram(3)

libram/_libram_cb_rm [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

_libram_cb_rm - search, remvoe, and return first callback 

                    with identifier id

SYNOPSIS

static struct _ram_cb_node *_libram_cb_rm(ram_cb h, long id)

DESCRIPTION

_libram_cb_rm(3) searches for the first node with session id id removes this node from the list and returns this node.

ARGUMENTS

RETURN

SEE ALSO

libram_cb_dispatch(3), ram_cb(3), _ram_cb_node(3), libram-cb(3), libram(3)

libram/_ram_cb [ Structures ]

[ Top ] [ libram ] [ Structures ]

NAME

_ram_cb - structure for callback list

DESCRIPTION

This structure defines the internal state that is used by the libram-cb(3) interface.

SOURCE

struct _ram_cb {
        struct libram_list cb_root;
        ram_fh fh;
};

ATTRIBUTES

SEE ALSO

libram_cb_init(3), libram_cb_exit(3), libram_cb_dispatch(3), libram_cb_register(3), libramrcb(3), ram_cb(3), libram(3)

libram/_ram_cb_node [ Structures ]

[ Top ] [ libram ] [ Structures ]

NAME

_ram_cb_node - node for the libram callback list

DESCRIPTION

For each callback registered with libram_callback(3) a node is added to the internal callback list. This callback list is later checked with libram_schedule_cb(3) if a callback can be activated.

This structure defines the parameters that are saved on the callback list.

SOURCE

struct _ram_cb_node {
        long id;
        long seq;
        void (*cb)(void*, char *, void*);
        void *arg;
        char *msg;
};

ATTRIBUTES

SEE ALSO

libram_cb_register(3), libram_cb_dispatch(3), libram-cb(3), libram(3)

libram/libram-cb [ Generics ]

[ Top ] [ libram ] [ Generics ]

NAME

libram-cb - callback handling for libram

SYNOPSIS

#include <libram.h>

DESCRIPTION

libram-cb(3) provides a callback framework for the asynchronous replies of libram(3). It manages a list of open requests. The list is initialized with libram_cb_init(3). If one of the libram_open(3), libram_data(3), or libram_close(3) returns NULL, i.e. the result is not immediate available, a callback can be registered using libram_cb_register(3). libram_cb_register(3) does not only register the callback, but also the msg and arg parameters to the libram_cb_register(3) call. arg and msg, together with the reply are later passed to the callback if a response is available. The arg parameter is later freed when the callback is activated. The msg parameter is used for debugging purposes.

The application can do other work until the response is available. The application can check if a response is available by using select(2) on the file descriptor returned by libram_fd(3).

If select(2) signals that a response is available, the application calls libram_cb_dispatch(3) to dispatch the reply. libram_cb_dispatch(3) uses libram_poll(3) to request the next reply, and then checks if there is a callback registered for the given identifier of the reply. If it finds a callback, the callback is activated with the reply and the registered arg and msg.

When the callback returns, libram_cb_dispatch(3) frees both, the request and the arguments.

EXAMPLE

void callback(void *arg, char *msg, void *reply)
{
...
}

ram_fh fh;
ram_cb ramcb = libram_cb_init(fh);

char *arg = malloc(...);
libram_cb_register(ramcb, id, callback, arg, "debug msg");
...
libram_cb_dispatch(ramcb);
...
libram_cb_exit(ramcb);

SEE ALSO

ram_cb(3), _ram_cb(3), _ram_cb_node(3), libram_cb_init(3), libram_cb_exit(3), libram_register_cb(3), libram_dispatch(3), _libram_cb_add(3), _libram_cb_dispatch(3), libram(3), libram_fd(3), libram_fdset(3), select(2)

libram/libram_cb_dispatch [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_cb_dispatch - read reply and call matching callback

SYNOPSIS

void libram_cb_dispatch(ram_cb h)

DESCRIPTION

libram_cb_dispatch handles the replies of libram(3). The program using libram should monitor libram replies by using select(2) on the libram file descriptor, see libram_fd(3).

When the program using libram determines input on the libram file descriptor, it should call libram_cb_dispatch(3). libram_cb_dispatch(3) calls libram_poll(3) to read the next reply and reads the identifier id from the reply. It searches for the next callback with the _libram_rm_cb(3) function for this identifier and calls the callback registered with libram_cb_register(3). NOTE The arg argument passed to libram_cb_register(3) is freed upon return of the callback.

ARGUMENTS

SEE ALSO

ram_cb(3), libram_cb_register(3), libram_poll(3), _libram_cb_rm(3), libram-cb(3), libram(3)

libram/libram_cb_exit [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_cb_exit - free libram callback managment

SYNOPSIS

void libram_cb_exit(ram_cb h)

DESCRIPTION

libram_cb_exit(3) frees the list of pending replies and deallocates the _ram_cb structure allocated by libram_cb_init(3). NOTE If there are pending entries of the callback list, this list is also freed. The arg component of the callback list is freed.

ARGUMENTS

SEE ALSO

libram_cb_init(3), ram_cb(3), _ram_cb(3), libram-cb(3), libram(3)

libram/libram_cb_init [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_cb_init - initalize libram callback managment

SYNOPSIS

ram_cb libram_cb_init(ram_fh fh)

DESCRIPTION

libram_cb_init(3) initializes the callback managment functions. It initialzes the list of pending requests and callback functions. The libram handle fh is used later by libram_cb_dispatch(3) to request the next reply structure using libram_poll(3).

The ram_cb handle returned by libram_cb_init(3) can be freed again using libram_cb_exit(3).

ARGUMENTS

RETURN

SEE ALSO

libram_cb_exit(3), libram_cb_register(3), libram_cb_dispatch(3), ram_cb(3), _ram_cb(3), libram-cb(3), libram(3)

libram/libram_cb_register [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_cb_register - register callback to callback list

SYNOPSIS

void *libram_cb_register(ram_cb h, long id, 
                void(*cb)(void* arg, char *msg, void* reply),
                void* arg, char *msg)

DESCRIPTION

libram_cb_register(3) adds a callback function to the list of pending results. The callback is activated by calling libram_cb_dispatch(3) when a response from the libram backend is available that corresponds to the session id.

The callback does not need to free the arg or reply arguments. These arguments are freed on return of the callback function in libram_cb_dispatch(3). NOTE The argument arg is passed to the callback function cb. When the callback has been activated, libram_cb_dispatch(3) frees arg. Thus, the argument must be allocated by the caller of libram_cb_register(3).

ARGUMENTS

RETURN

SEE ALSO

libram-cb(3), libram(3)