Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

ivykis(3) [debian man page]

ivykis(3)						    ivykis programmer's manual							 ivykis(3)

ivykis - library for asynchronous I/O readiness notification DESCRIPTION
ivykis is a library for asynchronous I/O readiness notification. It is a thin, portable wrapper around OS-provided mechanisms such as epoll_create(2), kqueue(2), poll(2), poll(7d) (/dev/poll), port_create(3C) and select(2). ivykis was mainly designed for building high-performance network applications, but can be used in any event-driven application that uses poll(2)able file descriptors as its event sources. While some programming models dictate using blocking I/O and starting a thread per event source, programs written to the ivykis API are generally single-threaded (or use only a small number of threads), and never block on I/O. All input and output is done in a nonblocking fashion, with I/O readiness notifications delivered via callback functions. The two main event sources in ivykis are file descriptors and timers. File descriptors generate an event when they become readable or writable or trigger an error condition, while timers generate an event when the system time increments past a certain pre-set time. Events associated with file descriptors are level-triggered -- a callback function set up to handle a certain file descriptor event will be called repeatedly until the condition generating the event has been cleared. As mentioned, applications using ivykis are generally single-threaded. Event callbacks are strictly serialised within a thread, and non- preemptible. This mostly removes the need for locking of shared data, and generally simplifies writing applications. Each thread that uses ivykis has its own file descriptors and timers, and runs a separate event loop. In ivykis, all code that is not initialization code runs from callback functions. Callback functions are not allowed to block. If a par- ticular piece of code wants to perform a certain operation that can block, it either has to schedule it to run in a separate thread, or it has to perform the operation in a nonblocking fashion instead. For example, registering an input callback function instead of blocking on a read, registering a timer instead of calling sleep(2), etc. In case of an internal error, ivykis will use iv_fatal(3) to report the error. The application can provide a custom fatal error handler by calling iv_set_fatal_msg_handler(3). SEE ALSO
iv_examples(3), iv_fatal(3), iv_fd(3), iv_timer(3), iv_task(3), iv_init(3), iv_main(3), iv_time(3) ivykis 2010-08-15 ivykis(3)

Check Out this Related Man Page

iv_fd(3)						    ivykis programmer's manual							  iv_fd(3)

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 descrip- tor, and a callback function for that event has been specified, that callback function will be called in the thread that the file descrip- tor 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 cur- rent 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. Con- versely, 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_han- dler_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 trans- ferring 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 suc- cessful 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 registra- tion 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) ivykis 2010-08-15 iv_fd(3)
Man Page