VirtualBox

source: vbox/trunk/include/iprt/poll.h@ 66599

Last change on this file since 66599 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.8 KB
Line 
1/** @file
2 * IPRT - Polling I/O Handles.
3 */
4
5/*
6 * Copyright (C) 2010-2016 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_poll_h
27#define ___iprt_poll_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_poll RTPoll - Polling I/O Handles
35 * @ingroup grp_rt
36 * @{
37 */
38
39/** @name Poll events
40 * @{ */
41/** Readable without blocking. */
42#define RTPOLL_EVT_READ RT_BIT_32(0)
43/** Writable without blocking. */
44#define RTPOLL_EVT_WRITE RT_BIT_32(1)
45/** Error condition, hangup, exception or similar. */
46#define RTPOLL_EVT_ERROR RT_BIT_32(2)
47/** Mask of the valid bits. */
48#define RTPOLL_EVT_VALID_MASK UINT32_C(0x00000007)
49/** @} */
50
51/**
52 * Polls on the specified poll set until an event occurs on one of the handles
53 * or the timeout expires.
54 *
55 * @returns IPRT status code.
56 * @retval VINF_SUCCESS if an event occurred on a handle. Note that these
57 * @retval VERR_INVALID_HANDLE if @a hPollSet is invalid.
58 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
59 * user is responsible for ensuring single threaded access.
60 * @retval VERR_TIMEOUT if @a cMillies ellapsed without any events.
61 * @retval VERR_DEADLOCK if @a cMillies is set to RT_INDEFINITE_WAIT and there
62 * are no valid handles in the set.
63 *
64 * @param hPollSet The set to poll on.
65 * @param cMillies Number of milliseconds to wait. Use
66 * RT_INDEFINITE_WAIT to wait for ever.
67 * @param pfEvents Where to return details about the events that
68 * occurred. Optional.
69 * @param pid Where to return the ID associated with the
70 * handle when calling RTPollSetAdd. Optional.
71 *
72 * @sa RTPollNoResume
73 *
74 * @remarks The caller is responsible for ensuring
75 */
76RTDECL(int) RTPoll(RTPOLLSET hPollSet, RTMSINTERVAL cMillies, uint32_t *pfEvents, uint32_t *pid);
77
78/**
79 * Same as RTPoll except that it will return when interrupted.
80 *
81 * @returns IPRT status code.
82 * @retval VINF_SUCCESS if an event occurred on a handle. Note that these
83 * @retval VERR_INVALID_HANDLE if @a hPollSet is invalid.
84 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
85 * user is responsible for ensuring single threaded access.
86 * @retval VERR_TIMEOUT if @a cMillies ellapsed without any events.
87 * @retval VERR_DEADLOCK if @a cMillies is set to RT_INDEFINITE_WAIT and there
88 * are no valid handles in the set.
89 * @retval VERR_INTERRUPTED if a signal or other asynchronous event interrupted
90 * the polling.
91 *
92 * @param hPollSet The set to poll on.
93 * @param cMillies Number of milliseconds to wait. Use
94 * RT_INDEFINITE_WAIT to wait for ever.
95 * @param pfEvents Where to return details about the events that
96 * occurred. Optional.
97 * @param pid Where to return the ID associated with the
98 * handle when calling RTPollSetAdd. Optional.
99 */
100RTDECL(int) RTPollNoResume(RTPOLLSET hPollSet, RTMSINTERVAL cMillies, uint32_t *pfEvents, uint32_t *pid);
101
102/**
103 * Creates a poll set with no members.
104 *
105 * @returns IPRT status code.
106 * @param phPollSet Where to return the poll set handle.
107 */
108RTDECL(int) RTPollSetCreate(PRTPOLLSET phPollSet);
109
110/**
111 * Destroys a poll set.
112 *
113 * @returns IPRT status code.
114 * @param hPollSet The poll set to destroy. NIL_POLLSET is quietly
115 * ignored (VINF_SUCCESS).
116 */
117RTDECL(int) RTPollSetDestroy(RTPOLLSET hPollSet);
118
119/**
120 * Adds a generic handle to the poll set.
121 *
122 * @returns IPRT status code
123 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
124 * user is responsible for ensuring single threaded access.
125 * @retval VERR_POLL_HANDLE_NOT_POLLABLE if the specified handle is not
126 * pollable.
127 * @retval VERR_POLL_HANDLE_ID_EXISTS if the handle ID is already in use in the
128 * set.
129 *
130 * @param hPollSet The poll set to modify.
131 * @param pHandle The handle to add. NIL handles are quietly
132 * ignored.
133 * @param fEvents Which events to poll for.
134 * @param id The handle ID.
135 */
136RTDECL(int) RTPollSetAdd(RTPOLLSET hPollSet, PCRTHANDLE pHandle, uint32_t fEvents, uint32_t id);
137
138/**
139 * Removes a generic handle from the poll set.
140 *
141 * @returns IPRT status code
142 * @retval VERR_INVALID_HANDLE if @a hPollSet not valid.
143 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
144 * user is responsible for ensuring single threaded access.
145 * @retval VERR_POLL_HANDLE_ID_NOT_FOUND if @a id doesn't resolve to a valid
146 * handle.
147 *
148 * @param hPollSet The poll set to modify.
149 * @param id The handle ID of the handle that should be
150 * removed.
151 */
152RTDECL(int) RTPollSetRemove(RTPOLLSET hPollSet, uint32_t id);
153
154
155/**
156 * Query a handle in the poll set by it's ID.
157 *
158 * @returns IPRT status code
159 * @retval VINF_SUCCESS if the handle was found. @a *pHandle is set.
160 * @retval VERR_INVALID_HANDLE if @a hPollSet is invalid.
161 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
162 * user is responsible for ensuring single threaded access.
163 * @retval VERR_POLL_HANDLE_ID_NOT_FOUND if there is no handle with that ID.
164 *
165 * @param hPollSet The poll set to query.
166 * @param id The ID of the handle.
167 * @param pHandle Where to return the handle details. Optional.
168 */
169RTDECL(int) RTPollSetQueryHandle(RTPOLLSET hPollSet, uint32_t id, PRTHANDLE pHandle);
170
171/**
172 * Gets the number of handles in the set.
173 *
174 * @retval The handle count.
175 * @retval UINT32_MAX if @a hPollSet is invalid or there is concurrent access.
176 *
177 * @param hPollSet The poll set.
178 */
179RTDECL(uint32_t) RTPollSetGetCount(RTPOLLSET hPollSet);
180
181/**
182 * Modifies the events to poll for for the given id.
183 *
184 * @returns IPRT status code.
185 * @retval VERR_INVALID_HANDLE if @a hPollSet not valid.
186 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
187 * user is responsible for ensuring single threaded access.
188 * @retval VERR_POLL_HANDLE_ID_NOT_FOUND if @a id doesn't resolve to a valid
189 * handle.
190 *
191 * @param hPollSet The poll set to modify.
192 * @param id The handle ID to change the events for.
193 * @param fEvents Which events to poll for.
194 */
195RTDECL(int) RTPollSetEventsChange(RTPOLLSET hPollSet, uint32_t id, uint32_t fEvents);
196
197/**
198 * Adds a pipe handle to the set.
199 *
200 * @returns See RTPollSetAdd.
201 *
202 * @param hPollSet The poll set.
203 * @param hPipe The pipe handle.
204 * @param fEvents Which events to poll for.
205 * @param id The handle ID.
206 *
207 * @todo Maybe we could figure out what to poll for depending on the kind of
208 * pipe we're dealing with.
209 */
210DECLINLINE(int) RTPollSetAddPipe(RTPOLLSET hPollSet, RTPIPE hPipe, uint32_t fEvents, uint32_t id)
211{
212 RTHANDLE Handle;
213 Handle.enmType = RTHANDLETYPE_PIPE;
214 Handle.u.uInt = 0;
215 Handle.u.hPipe = hPipe;
216 return RTPollSetAdd(hPollSet, &Handle, fEvents, id);
217}
218
219/**
220 * Adds a socket handle to the set.
221 *
222 * @returns See RTPollSetAdd.
223 *
224 * @param hPollSet The poll set.
225 * @param hSocket The socket handle.
226 * @param fEvents Which events to poll for.
227 * @param id The handle ID.
228 */
229DECLINLINE(int) RTPollSetAddSocket(RTPOLLSET hPollSet, RTSOCKET hSocket, uint32_t fEvents, uint32_t id)
230{
231 RTHANDLE Handle;
232 Handle.enmType = RTHANDLETYPE_SOCKET;
233 Handle.u.uInt = 0;
234 Handle.u.hSocket = hSocket;
235 return RTPollSetAdd(hPollSet, &Handle, fEvents, id);
236}
237
238/** @} */
239
240RT_C_DECLS_END
241
242#endif
243
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette