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(const 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, iv_fatal(2) 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)