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


6       iv_fd_register, iv_fd_register_try, iv_fd_unregister, iv_fd_registered,
7       iv_fd_set_handler_in,  iv_fd_set_handler_err,  iv_fd_set_handler_out  -
8       deal with ivykis file descriptors


11       #include <iv.h>
13       struct iv_fd {
14               int             fd;
15               void            *cookie;
16               void            (*handler_in)(void *);
17               void            (*handler_out)(void *);
18               void            (*handler_err)(void *);
19       };
21       void IV_FD_INIT(struct iv_fd *fd);
22       void iv_fd_register(struct iv_fd *fd);
23       int iv_fd_register_try(struct iv_fd *fd);
24       void iv_fd_unregister(struct iv_fd *fd);
25       int iv_fd_registered(const struct iv_fd *fd);
26       void iv_fd_set_handler_in(struct iv_fd *fd, void (*handler)(void *));
27       void iv_fd_set_handler_out(struct iv_fd *fd, void (*handler)(void *));
28       void iv_fd_set_handler_err(struct iv_fd *fd, void (*handler)(void *));


31       The  functions  iv_fd_register  and  iv_fd_unregister register, respec‐
32       tively unregister, a file descriptor with the current  thread's  ivykis
33       event loop.  Calling iv_fd_registered on a file descriptor returns true
34       if that file descriptor is currently registered with ivykis.
36       When a file descriptor that is registered with ivykis becomes ready for
37       input  or output, or an error condition occurs on that file descriptor,
38       and a callback function for that event has been specified,  that  call‐
39       back function will be called in the thread that the file descriptor was
40       registered in.
42       And conversely, when a file descriptor that is already ready for  input
43       or  output  or  already  has  an error condition set is registered with
44       ivykis, and the corresponding callback function pointer  is  not  NULL,
45       the  callback function will be called in the next iteration of the cur‐
46       rent thread's ivykis event loop.
48       Before a file descriptor is registered, it must have  been  initialised
49       by  calling  IV_FD_INIT  on it, and must have had its ->fd member field
50       set to a valid OS file descriptor.  The ->handler_in, ->handler_out and
51       ->handler_err  member fields point to callback functions that are to be
52       called when the specified file descriptor becomes ready  for  input  or
53       output or an error condition occurs.  If any handler function is set to
54       NULL, it indicates that the application  is  not  interested  in  being
55       notified of the corresponding event.
57       An  application  is  not allowed to change the ->fd member while a file
58       descriptor is registered.
60       iv_fd_set_handler_in changes the callback function to  be  called  when
61       descriptor  fd  becomes ready for input.  An application is not allowed
62       to directly change the ->handler_in member after  the  file  descriptor
63       has been registered, this function has to be used instead.  Conversely,
64       it is not allowed to use this function before the file  descriptor  has
65       been registered.
67       iv_fd_set_handler_out  is  analogous  to  iv_fd_set_handler_in, only it
68       deals with the callback function for output readiness (->handler_out).
70       iv_fd_set_handler_err  is   analogous   to   iv_fd_set_handler_in   and
71       iv_fd_set_handler_out,  only  it  deals  with the callback function for
72       error conditions (->handler_err).
74       When a handler function was NULL, and was set to a  non-NULL  value  by
75       calling  iv_fd_set_handler_in,  iv_fd_set_handler_out or iv_fd_set_han‐
76       dler_err, and the file descriptor was already ready for input  or  out‐
77       put,  or already had an error condition set, an event is generated, and
78       the specified callback function will be called in the next iteration of
79       the current thread's event loop.  The application does not need to poll
80       the file descriptor to see if a condition was already raised.
82       Callback functions are passed a cookie value as their  first  and  sole
83       argument.  If the application wishes to use this facility for transfer‐
84       ring data to the callback function, it should set the  ->cookie  member
85       of a file descriptor to a value of type void *.  This value can be mod‐
86       ified directly by the application at any time without calling a  helper
87       function.
89       When  a  file descriptor is registered with ivykis, it is transparently
90       set to nonblocking mode, and configured to be closed on exit(3).
92       An application is allowed to unregister a file descriptor  from  within
93       any  callback  function, including callback functions triggered by that
94       file descriptor itself, and even to free the  memory  corresponding  to
95       that file descriptor from any callback function, but a struct iv_fd can
96       only be unregistered in the thread that it was registered from.
98       It is allowed to register the same underlying  OS  file  descriptor  in
99       multiple  threads,  but  a given struct iv_fd can only be registered in
100       one thread at a time.
102       iv_fd_register does not return errors to the caller, and in case of  an
103       error  while  registering  the file descriptor, for example if it isn't
104       open or is unpollable, iv_fatal(2) will be invoked.  If it is not known
105       whether  registering  the  file descriptor with the kernel will be suc‐
106       cessful or not, use iv_fd_register_try instead, which is a  variant  on
107       iv_fd_register  which returns a nonzero value in case of a registration
108       error.  Since iv_fd_register_try disables  various  internal  optimisa‐
109       tions, it is recommended to use iv_fd_register whenever possible.
111       See iv_examples(3) for programming examples.


114       ivykis(3), iv_examples(3)
118ivykis                            2010-08-15                          iv_fd(3)