NAME¶
iv_fd_register, iv_fd_register_try, iv_fd_unregister, iv_fd_registered,
iv_fd_set_handler_in, iv_fd_set_handler_err, iv_fd_set_handler_out - deal with
ivykis file descriptors
SYNOPSIS¶
#include <iv.h>
struct iv_fd {
int fd;
void *cookie;
void (*handler_in)(void *);
void (*handler_out)(void *);
void (*handler_err)(void *);
};
void IV_FD_INIT(struct iv_fd *fd);
void iv_fd_register(struct iv_fd *fd);
int iv_fd_register_try(struct iv_fd *fd);
void iv_fd_unregister(struct iv_fd *fd);
int iv_fd_registered(struct iv_fd *fd);
void iv_fd_set_handler_in(struct iv_fd *fd, void
(*handler)(void *));
void iv_fd_set_handler_out(struct iv_fd *fd, void
(*handler)(void *));
void iv_fd_set_handler_err(struct iv_fd *fd, void
(*handler)(void *));
DESCRIPTION¶
The functions
iv_fd_register and
iv_fd_unregister register,
respectively unregister, a file descriptor with the current thread's ivykis
event loop. Calling
iv_fd_registered on a file descriptor returns true
if that file descriptor is currently registered with ivykis.
When a file descriptor that is registered with ivykis becomes ready for input or
output, or an error condition occurs on that file descriptor, and a callback
function for that event has been specified, that callback function will be
called in the thread that the file descriptor was registered in.
And conversely, when a file descriptor that is already ready for input or output
or already has an error condition set is registered with ivykis, and the
corresponding callback function pointer is not NULL, the callback function
will be called in the next iteration of the current thread's ivykis event
loop.
Before a file descriptor is registered, it must have been initialised by calling
IV_FD_INIT on it, and must have had its
->fd member field set
to a valid OS file descriptor. The
->handler_in, ->handler_out
and
->handler_err member fields point to callback functions that are
to be called when the specified file descriptor becomes ready for input or
output or an error condition occurs. If any handler function is set to
NULL, it indicates that the application is not interested in being
notified of the corresponding event.
An application is not allowed to change the
->fd member while a file
descriptor is registered.
iv_fd_set_handler_in changes the callback function to be called when
descriptor
fd becomes ready for input. An application is not allowed to
directly change the
->handler_in member after the file descriptor
has been registered, this function has to be used instead. Conversely, it is
not allowed to use this function before the file descriptor has been
registered.
iv_fd_set_handler_out is analogous to
iv_fd_set_handler_in, only
it deals with the callback function for output readiness
(->handler_out).
iv_fd_set_handler_err is analogous to
iv_fd_set_handler_in and
iv_fd_set_handler_out, only it deals with the callback function for
error conditions
(->handler_err).
When a handler function was NULL, and was set to a non-NULL value by calling
iv_fd_set_handler_in, iv_fd_set_handler_out or
iv_fd_set_handler_err, and the file descriptor was already ready for
input or output, or already had an error condition set, an event is generated,
and the specified callback function will be called in the next iteration of
the current thread's event loop. The application does not need to poll the
file descriptor to see if a condition was already raised.
Callback functions are passed a
cookie value as their first and sole
argument. If the application wishes to use this facility for transferring data
to the callback function, it should set the
->cookie member of a
file descriptor to a value of type
void *. This value can be modified
directly by the application at any time without calling a helper function.
When a file descriptor is registered with ivykis, it is transparently set to
nonblocking mode, and configured to be closed on
exit(3).
An application is allowed to unregister a file descriptor from within any
callback function, including callback functions triggered by that file
descriptor itself, and even to free the memory corresponding to that file
descriptor from any callback function, but a
struct iv_fd can only be
unregistered in the thread that it was registered from.
It is allowed to register the same underlying OS file descriptor in multiple
threads, but a given
struct iv_fd can only be registered in one thread
at a time.
iv_fd_register does not return errors to the caller, and in case of an
error while registering the file descriptor, for example if it isn't open or
is unpollable,
abort(3) will be invoked. If it is not known whether
registering the file descriptor with the kernel will be successful or not, use
iv_fd_register_try instead, which is a variant on
iv_fd_register
which returns a nonzero value in case of a registration error. Since
iv_fd_register_try disables various internal optimisations, it is
recommended to use
iv_fd_register whenever possible.
See
iv_examples(3) for programming examples.
SEE ALSO¶
ivykis(3),
iv_examples(3)