GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


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)



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.085 seconds. Last modified: November 04 2018 12:49:43.