IO Event Handling

IO Event Handling — Functions to support asynchronous I/O

Synopsis


#include <monitor/monitor.h>


void        (*mon_io_cb)                    (int fd,
                                             mon_io_events events,
                                             void *ptr);
enum        mon_io_events;
int         mon_io_add                      (int fd,
                                             mon_io_cb cb,
                                             void *user_data);
int         mon_io_set_events               (int fd,
                                             mon_io_events to_set,
                                             mon_io_events to_clear);
int         mon_io_set_aux                  (int fd,
                                             void *ptr);
void*       mon_io_get_aux                  (int fd);
int         mon_io_remove                   (int fd);
int         mon_io_replace                  (int oldfd,
                                             int newfd);
void        mon_io_remove_all               (void);
int         mon_io_wait_events              (int timeout);
int         mon_io_wait_fd                  (int fd,
                                             mon_io_events events,
                                             int restart);
int         mon_io_wait_fd_timeout          (int fd,
                                             mon_io_events events,
                                             int timeout,
                                             int restart);

Description

Details

mon_io_cb ()

void        (*mon_io_cb)                    (int fd,
                                             mon_io_events events,
                                             void *ptr);

Specifies the type of the function which is passed to mon_io_set_cb().

This function is passed the file descriptor which caused an event, an event mask and an opaque pointer originally passed to mon_io_set_cb().

`fd` :	the file descriptor having an outstanding event.
`events` :	the event mask.
`ptr` :	the opaque pointer passed to `mon_io_set_cb()`.

enum mon_io_events

typedef enum {
	MON_IO_READ		= (1 << 0),
	MON_IO_WRITE		= (1 << 1),
	MON_IO_ERROR		= (1 << 2)
} mon_io_events;

I/O events to handle.

`MON_IO_READ`	a file descriptor has data ready for reading.
`MON_IO_WRITE`	a file desrciptor is ready for writing.
`MON_IO_ERROR`	a file descriptor has an error condition.

mon_io_add ()

int         mon_io_add                      (int fd,
                                             mon_io_cb cb,
                                             void *user_data);

Adds a file descriptor to the set of descriptors to be monitored for events.

`fd` :	the descriptor to add.
`cb` :	the callback function to call when an event occurs with the descriptor.
`user_data` :	opaque pointer to associate with the descriptor. It will be passed to the `mon_io_cb()` functions.
Returns :	0 or an error code.

mon_io_set_events ()

int         mon_io_set_events               (int fd,
                                             mon_io_events to_set,
                                             mon_io_events to_clear);

Adds events to the set of watched events. You must call mon_io_add() with the same fd parameter before calling this function.

`fd` :	a file descriptor.
`to_set` :	the events to watch for. Must be the combination of `MON_IO_READ`, `MON_IO_WRITE` and `MON_IO_ERROR`.
`to_clear` :	the events to stop watching for. Must be the combination of `MON_IO_READ`, `MON_IO_WRITE` and `MON_IO_ERROR`.
Returns :	0 or an error code.

mon_io_set_aux ()

int         mon_io_set_aux                  (int fd,
                                             void *ptr);

Modifies the auxiliary data associated with the fd file descriptor.

`fd` :	a file descriptor.
`ptr` :	the pointer to associate with the descriptor.
Returns :	0 or an error code.

mon_io_get_aux ()

void*       mon_io_get_aux                  (int fd);

Returns the auxiliary data associated with the fd file descriptor.

`fd` :	a file descriptor.
Returns :

mon_io_remove ()

int         mon_io_remove                   (int fd);

Stops monitoring a file descriptor.

`fd` :	a file descriptor.
Returns :	0 or an error code.

mon_io_replace ()

int         mon_io_replace                  (int oldfd,
                                             int newfd);

Replaces a file descriptor with another while keeping the callback function and the mask of watched events.

`oldfd` :	the old file descriptor.
`newfd` :	the new file descriptor.
Returns :	0 if successful or an error code.

mon_io_remove_all ()

void        mon_io_remove_all               (void);

Stops monitoring all descriptors. Should only be called when shutting down the library.

mon_io_wait_events ()

int         mon_io_wait_events              (int timeout);

Monitors file descriptors for events and call the appropriate callbacks if neccessary.

`timeout` :	wait timeout.
Returns :	0 or an error code.

mon_io_wait_fd ()

int         mon_io_wait_fd                  (int fd,
                                             mon_io_events events,
                                             int restart);

Waits for an event on a file descriptor.

`fd` :	the file descriptor to watch.
`events` :	the events to look for. Must be the combination of `MON_IO_READ`, `MON_IO_WRITE` and `MON_IO_ERROR`.
`restart` :	if true the function will not terminate if the waiting is interrupted by a signal.
Returns :	0 or an error code.

mon_io_wait_fd_timeout ()

int         mon_io_wait_fd_timeout          (int fd,
                                             mon_io_events events,
                                             int timeout,
                                             int restart);

Waits for an event on a file descriptor, with a possible timeout.

`fd` :	the file descriptor to watch.
`events` :	the events to look for. Must be the combination of `MON_IO_READ`, `MON_IO_WRITE` and `MON_IO_ERROR`.
`timeout` :	timeout in milliseconds. If the value is negative, there will be no timeout. If the value is zero, the function returns immediately.
`restart` :	if true the function will not terminate if the waiting is interrupted by a signal.
Returns :	0 if an event is received, `MON_ERR_TIMEOUT` if the timeout is expired before an event occured, or an error code.