1iv_fd(3) ivykis programmer's manual iv_fd(3)
2
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
9
11 #include <iv.h>
12 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 };
20 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 *));
29
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.
35 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.
41 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.
47 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.
56 An application is not allowed to change the ->fd member while a file
58 descriptor is registered.
59 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.
66 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).
69 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).
73 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.
81 Callback functions are passed a cookie value as their first and sole
83 argument.