VirtualBox

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

Last change on this file since 77821 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.4 KB
Line 
1/** @file
2 * IPRT - Polling I/O Handles.
3 */
4
5/*
6 * Copyright (C) 2010-2019 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_INCLUDED_poll_h
27#define IPRT_INCLUDED_poll_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34
35RT_C_DECLS_BEGIN
36
37/** @defgroup grp_rt_poll RTPoll - Polling I/O Handles
38 * @ingroup grp_rt
39 * @{
40 */
41
42/** @name Poll events
43 * @{ */
44/** Readable without blocking. */
45#define RTPOLL_EVT_READ RT_BIT_32(0)
46/** Writable without blocking. */
47#define RTPOLL_EVT_WRITE RT_BIT_32(1)
48/** Error condition, hangup, exception or similar. */
49#define RTPOLL_EVT_ERROR RT_BIT_32(2)
50/** Mask of the valid bits. */
51#define RTPOLL_EVT_VALID_MASK UINT32_C(0x00000007)
52/** @} */
53
54/**
55 * Polls on the specified poll set until an event occurs on one of the handles
56 * or the timeout expires.
57 *
58 * @returns IPRT status code.
59 * @retval VINF_SUCCESS if an event occurred on a handle. Note that these
60 * @retval VERR_INVALID_HANDLE if @a hPollSet is invalid.
61 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
62 * user is responsible for ensuring single threaded access.
63 * @retval VERR_TIMEOUT if @a cMillies ellapsed without any events.
64 * @retval VERR_DEADLOCK if @a cMillies is set to RT_INDEFINITE_WAIT and there
65 * are no valid handles in the set.
66 *
67 * @param hPollSet The set to poll on.
68 * @param cMillies Number of milliseconds to wait. Use
69 * RT_INDEFINITE_WAIT to wait for ever.
70 * @param pfEvents Where to return details about the events that
71 * occurred. Optional.
72 * @param pid Where to return the ID associated with the
73 * handle when calling RTPollSetAdd. Optional.
74 *
75 * @sa RTPollNoResume
76 *
77 * @remarks The caller is responsible for ensuring
78 */
79RTDECL(int) RTPoll(RTPOLLSET hPollSet, RTMSINTERVAL cMillies, uint32_t *pfEvents, uint32_t *pid);
80
81/**
82 * Same as RTPoll except that it will return when interrupted.
83 *
84 * @returns IPRT status code.
85 * @retval VINF_SUCCESS if an event occurred on a handle. Note that these
86 * @retval VERR_INVALID_HANDLE if @a hPollSet is invalid.
87 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
88 * user is responsible for ensuring single threaded access.
89 * @retval VERR_TIMEOUT if @a cMillies ellapsed without any events.
90 * @retval VERR_DEADLOCK if @a cMillies is set to RT_INDEFINITE_WAIT and there
91 * are no valid handles in the set.
92 * @retval VERR_INTERRUPTED if a signal or other asynchronous event interrupted
93 * the polling.
94 *
95 * @param hPollSet The set to poll on.
96 * @param cMillies Number of milliseconds to wait. Use
97 * RT_INDEFINITE_WAIT to wait for ever.
98 * @param pfEvents Where to return details about the events that
99 * occurred. Optional.
100 * @param pid Where to return the ID associated with the
101 * handle when calling RTPollSetAdd. Optional.
102 */
103RTDECL(int) RTPollNoResume(RTPOLLSET hPollSet, RTMSINTERVAL cMillies, uint32_t *pfEvents, uint32_t *pid);
104
105/**
106 * Creates a poll set with no members.
107 *
108 * @returns IPRT status code.
109 * @param phPollSet Where to return the poll set handle.
110 */
111RTDECL(int) RTPollSetCreate(PRTPOLLSET phPollSet);
112
113/**
114 * Destroys a poll set.
115 *
116 * @returns IPRT status code.
117 * @param hPollSet The poll set to destroy. NIL_POLLSET is quietly
118 * ignored (VINF_SUCCESS).
119 */
120RTDECL(int) RTPollSetDestroy(RTPOLLSET hPollSet);
121
122/**
123 * Adds a generic handle to the poll set.
124 *
125 * If a handle is entered more than once, it is recommended to add the one with
126 * RTPOLL_EVT_ERROR first to ensure that you get the right ID back when an error
127 * actually occurs. On some hosts it is possible that polling for
128 * RTPOLL_EVT_READ on a socket may cause it to return error conditions because
129 * the two cannot so easily be distinguished.
130 *
131 * Also note that RTPOLL_EVT_ERROR may be returned by RTPoll even if not asked
132 * for.
133 *
134 * @returns IPRT status code
135 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
136 * user is responsible for ensuring single threaded access.
137 * @retval VERR_POLL_HANDLE_NOT_POLLABLE if the specified handle is not
138 * pollable.
139 * @retval VERR_POLL_HANDLE_ID_EXISTS if the handle ID is already in use in the
140 * set.
141 *
142 * @param hPollSet The poll set to modify.
143 * @param pHandle The handle to add. NIL handles are quietly
144 * ignored.
145 * @param fEvents Which events to poll for.
146 * @param id The handle ID.
147 */
148RTDECL(int) RTPollSetAdd(RTPOLLSET hPollSet, PCRTHANDLE pHandle, uint32_t fEvents, uint32_t id);
149
150/**
151 * Removes a generic handle from the poll set.
152 *
153 * @returns IPRT status code
154 * @retval VERR_INVALID_HANDLE if @a hPollSet not valid.
155 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
156 * user is responsible for ensuring single threaded access.
157 * @retval VERR_POLL_HANDLE_ID_NOT_FOUND if @a id doesn't resolve to a valid
158 * handle.
159 *
160 * @param hPollSet The poll set to modify.
161 * @param id The handle ID of the handle that should be
162 * removed.
163 */
164RTDECL(int) RTPollSetRemove(RTPOLLSET hPollSet, uint32_t id);
165
166
167/**
168 * Query a handle in the poll set by it's ID.
169 *
170 * @returns IPRT status code
171 * @retval VINF_SUCCESS if the handle was found. @a *pHandle is set.
172 * @retval VERR_INVALID_HANDLE if @a hPollSet is invalid.
173 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
174 * user is responsible for ensuring single threaded access.
175 * @retval VERR_POLL_HANDLE_ID_NOT_FOUND if there is no handle with that ID.
176 *
177 * @param hPollSet The poll set to query.
178 * @param id The ID of the handle.
179 * @param pHandle Where to return the handle details. Optional.
180 */
181RTDECL(int) RTPollSetQueryHandle(RTPOLLSET hPollSet, uint32_t id, PRTHANDLE pHandle);
182
183/**
184 * Gets the number of handles in the set.
185 *
186 * @retval The handle count.
187 * @retval UINT32_MAX if @a hPollSet is invalid or there is concurrent access.
188 *
189 * @param hPollSet The poll set.
190 */
191RTDECL(uint32_t) RTPollSetGetCount(RTPOLLSET hPollSet);
192
193/**
194 * Modifies the events to poll for for the given id.
195 *
196 * @returns IPRT status code.
197 * @retval VERR_INVALID_HANDLE if @a hPollSet not valid.
198 * @retval VERR_CONCURRENT_ACCESS if another thread is already accessing the set. The
199 * user is responsible for ensuring single threaded access.
200 * @retval VERR_POLL_HANDLE_ID_NOT_FOUND if @a id doesn't resolve to a valid
201 * handle.
202 *
203 * @param hPollSet The poll set to modify.
204 * @param id The handle ID to change the events for.
205 * @param fEvents Which events to poll for.
206 */
207RTDECL(int) RTPollSetEventsChange(RTPOLLSET hPollSet, uint32_t id, uint32_t fEvents);
208
209/**
210 * Adds a pipe handle to the set.
211 *
212 * @returns See RTPollSetAdd.
213 *
214 * @param hPollSet The poll set.
215 * @param hPipe The pipe handle.
216 * @param fEvents Which events to poll for.
217 * @param id The handle ID.
218 *
219 * @todo Maybe we could figure out what to poll for depending on the kind of
220 * pipe we're dealing with.
221 */
222DECLINLINE(int) RTPollSetAddPipe(RTPOLLSET hPollSet, RTPIPE hPipe, uint32_t fEvents, uint32_t id)
223{
224 RTHANDLE Handle;
225 Handle.enmType = RTHANDLETYPE_PIPE;
226 Handle.u.uInt = 0;
227 Handle.u.hPipe = hPipe;
228 return RTPollSetAdd(hPollSet, &Handle, fEvents, id);
229}
230
231/**
232 * Adds a socket handle to the set.
233 *
234 * @returns See RTPollSetAdd.
235 *
236 * @param hPollSet The poll set.
237 * @param hSocket The socket handle.
238 * @param fEvents Which events to poll for.
239 * @param id The handle ID.
240 */
241DECLINLINE(int) RTPollSetAddSocket(RTPOLLSET hPollSet, RTSOCKET hSocket, uint32_t fEvents, uint32_t id)
242{
243 RTHANDLE Handle;
244 Handle.enmType = RTHANDLETYPE_SOCKET;
245 Handle.u.uInt = 0;
246 Handle.u.hSocket = hSocket;
247 return RTPollSetAdd(hPollSet, &Handle, fEvents, id);
248}
249
250/** @} */
251
252RT_C_DECLS_END
253
254#endif /* !IPRT_INCLUDED_poll_h */
255
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