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)