1/*
2 * Copyright © 2016 Keith Packard
3 *
4 * Permission to use, copy, modify, distribute, and sell this software and its
5 * documentation for any purpose is hereby granted without fee, provided that
6 * the above copyright notice appear in all copies and that both that copyright
7 * notice and this permission notice appear in supporting documentation, and
8 * that the name of the copyright holders not be used in advertising or
9 * publicity pertaining to distribution of the software without specific,
10 * written prior permission.  The copyright holders make no representations
11 * about the suitability of this software for any purpose.  It is provided "as
12 * is" without express or implied warranty.
13 *
14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
20 * OF THIS SOFTWARE.
21 */
22
23#ifndef _OSPOLL_H_
24#define _OSPOLL_H_
25
26/* Forward declaration */
27struct ospoll;
28
29/**
30 * ospoll_wait trigger mode
31 *
32 * @ospoll_trigger_edge
33 *      Trigger only when going from no data available
34 *      to data available.
35 *
36 * @ospoll_trigger_level
37 *      Trigger whenever there is data available
38 */
39enum ospoll_trigger {
40    ospoll_trigger_edge,
41    ospoll_trigger_level
42};
43
44/**
45 * Create a new ospoll structure
46 */
47struct ospoll *
48ospoll_create(void);
49
50/**
51 * Destroy an ospoll structure
52 *
53 * @param       ospoll          ospoll to destroy
54 */
55void
56ospoll_destroy(struct ospoll *ospoll);
57
58/**
59 * Add a file descriptor to monitor
60 *
61 * @param       ospoll          ospoll to add to
62 * @param       fd              File descriptor to monitor
63 * @param       trigger         Trigger mode for ospoll_wait
64 * @param       callback        Function to call when triggered
65 * @param       data            Extra data to pass callback
66 */
67Bool
68ospoll_add(struct ospoll *ospoll, int fd,
69           enum ospoll_trigger trigger,
70           void (*callback)(int fd, int xevents, void *data),
71           void *data);
72
73/**
74 * Remove a monitored file descriptor
75 *
76 * @param       ospoll          ospoll to remove from
77 * @param       fd              File descriptor to stop monitoring
78 */
79void
80ospoll_remove(struct ospoll *ospoll, int fd);
81
82/**
83 * Listen on additional events
84 *
85 * @param       ospoll          ospoll monitoring fd
86 * @param       fd              File descriptor to change
87 * @param       events          Additional events to trigger on
88 */
89void
90ospoll_listen(struct ospoll *ospoll, int fd, int xevents);
91
92/**
93 * Stop listening on events
94 *
95 * @param       ospoll          ospoll monitoring fd
96 * @param       fd              File descriptor to change
97 * @param       events          events to stop triggering on
98 */
99void
100ospoll_mute(struct ospoll *ospoll, int fd, int xevents);
101
102/**
103 * Wait for events
104 *
105 * @param       ospoll          ospoll to wait on
106 * @param       timeout         < 0 wait forever
107 *                              = 0 check and return
108 *                              > 0 timeout in milliseconds
109 * @return      < 0 error
110 *              = 0 timeout
111 *              > 0 number of events delivered
112 */
113int
114ospoll_wait(struct ospoll *ospoll, int timeout);
115
116/**
117 * Reset edge trigger status
118 *
119 * @param       ospoll          ospoll monitoring fd
120 * @param       fd              file descriptor
121 *
122 * ospoll_reset_events resets the state of an edge-triggered
123 * fd so that ospoll_wait calls will report events again.
124 *
125 * Call this after a read/recv operation reports no more data available.
126 */
127void
128ospoll_reset_events(struct ospoll *ospoll, int fd);
129
130/**
131 * Fetch the data associated with an fd
132 *
133 * @param       ospoll          ospoll monitoring fd
134 * @param       fd              file descriptor
135 *
136 * @return      data parameter passed to ospoll_add call on
137 *              this file descriptor
138 */
139void *
140ospoll_data(struct ospoll *ospoll, int fd);
141
142#endif /* _OSPOLL_H_ */
143