VirtualBox

source: vbox/trunk/include/iprt/req.h@ 29282

Last change on this file since 29282 was 28800, checked in by vboxsync, 15 years ago

Automated rebranding to Oracle copyright/license strings via filemuncher

  • Property eol-style set to native
  • Property svn:eol-style set to native
File size: 13.1 KB
Line 
1/** @file
2 * IPRT - Request packets
3 */
4
5/*
6 * Copyright (C) 2006-2007 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_req_h
27#define ___iprt_req_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32#include <iprt/stdarg.h>
33
34RT_C_DECLS_BEGIN
35
36/** @defgroup grp_rt_req RTReq - Request Packet Management
37 * @ingroup grp_rt
38 * @{
39 */
40
41/**
42 * Request type.
43 */
44typedef enum RTREQTYPE
45{
46 /** Invalid request. */
47 RTREQTYPE_INVALID = 0,
48 /** RT: Internal. */
49 RTREQTYPE_INTERNAL,
50 /** Maximum request type (exclusive). Used for validation. */
51 RTREQTYPE_MAX
52} RTREQTYPE;
53
54/**
55 * Request state.
56 */
57typedef enum RTREQSTATE
58{
59 /** The state is invalid. */
60 RTREQSTATE_INVALID = 0,
61 /** The request have been allocated and is in the process of being filed. */
62 RTREQSTATE_ALLOCATED,
63 /** The request is queued by the requester. */
64 RTREQSTATE_QUEUED,
65 /** The request is begin processed. */
66 RTREQSTATE_PROCESSING,
67 /** The request is completed, the requester is begin notified. */
68 RTREQSTATE_COMPLETED,
69 /** The request packet is in the free chain. (The requester */
70 RTREQSTATE_FREE
71} RTREQSTATE;
72
73/**
74 * Request flags.
75 */
76typedef enum RTREQFLAGS
77{
78 /** The request returns a iprt status code. */
79 RTREQFLAGS_IPRT_STATUS = 0,
80 /** The request is a void request and have no status code. */
81 RTREQFLAGS_VOID = 1,
82 /** Return type mask. */
83 RTREQFLAGS_RETURN_MASK = 1,
84 /** Caller does not wait on the packet, Queue process thread will free it. */
85 RTREQFLAGS_NO_WAIT = 2
86} RTREQFLAGS;
87
88/** Pointer to a request queue. */
89typedef struct RTREQQUEUE *PRTREQQUEUE;
90
91/**
92 * RT Request packet.
93 *
94 * This is used to request an action in the queue handler thread.
95 */
96typedef struct RTREQ
97{
98 /** Pointer to the next request in the chain. */
99 struct RTREQ * volatile pNext;
100 /** Pointer to the queue this packet belongs to. */
101 PRTREQQUEUE pQueue;
102 /** Request state. */
103 volatile RTREQSTATE enmState;
104 /** iprt status code for the completed request. */
105 volatile int iStatus;
106 /** Requester event sem.
107 * The request can use this event semaphore to wait/poll for completion
108 * of the request.
109 */
110 RTSEMEVENT EventSem;
111 /** Set if the event semaphore is clear. */
112 volatile bool fEventSemClear;
113 /** Flags, RTREQ_FLAGS_*. */
114 unsigned fFlags;
115 /** Request type. */
116 RTREQTYPE enmType;
117 /** Request specific data. */
118 union RTREQ_U
119 {
120 /** RTREQTYPE_INTERNAL. */
121 struct
122 {
123 /** Pointer to the function to be called. */
124 PFNRT pfn;
125 /** Number of arguments. */
126 unsigned cArgs;
127 /** Array of arguments. */
128 uintptr_t aArgs[64];
129 } Internal;
130 } u;
131} RTREQ;
132/** Pointer to an RT request packet. */
133typedef RTREQ *PRTREQ;
134
135/** @todo hide this */
136typedef struct RTREQQUEUE
137{
138 /** Head of the request queue. Atomic. */
139 volatile PRTREQ pReqs;
140 /** The last index used during alloc/free. */
141 volatile uint32_t iReqFree;
142 /** Number of free request packets. */
143 volatile uint32_t cReqFree;
144 /** Array of pointers to lists of free request packets. Atomic. */
145 volatile PRTREQ apReqFree[9];
146 /** Requester event sem.
147 * The request can use this event semaphore to wait/poll for new requests.
148 */
149 RTSEMEVENT EventSem;
150 /** Set if busy (pending or processing requests). */
151 bool volatile fBusy;
152} RTREQQUEUE;
153
154#ifdef IN_RING3
155
156/**
157 * Create a request packet queueu
158 *
159 * @returns iprt status code.
160 * @param ppQueue Where to store the request queue pointer.
161 */
162RTDECL(int) RTReqCreateQueue(PRTREQQUEUE *ppQueue);
163
164
165/**
166 * Destroy a request packet queueu
167 *
168 * @returns iprt status code.
169 * @param pQueue The request queue.
170 */
171RTDECL(int) RTReqDestroyQueue(PRTREQQUEUE pQueue);
172
173
174/**
175 * Process one or more request packets
176 *
177 * @returns iprt status code.
178 * @returns VERR_TIMEOUT if cMillies was reached without the packet being added.
179 *
180 * @param pQueue The request queue.
181 * @param cMillies Number of milliseconds to wait for a pending request.
182 * Use RT_INDEFINITE_WAIT to only wait till one is added.
183 */
184RTDECL(int) RTReqProcess(PRTREQQUEUE pQueue, RTMSINTERVAL cMillies);
185
186
187/**
188 * Allocate and queue a call request.
189 *
190 * If it's desired to poll on the completion of the request set cMillies
191 * to 0 and use RTReqWait() to check for completation. In the other case
192 * use RT_INDEFINITE_WAIT.
193 * The returned request packet must be freed using RTReqFree().
194 *
195 * @returns iprt statuscode.
196 * Will not return VERR_INTERRUPTED.
197 * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
198 *
199 * @param pQueue The request queue.
200 * @param ppReq Where to store the pointer to the request.
201 * This will be NULL or a valid request pointer not matter what happends.
202 * @param cMillies Number of milliseconds to wait for the request to
203 * be completed. Use RT_INDEFINITE_WAIT to only
204 * wait till it's completed.
205 * @param pfnFunction Pointer to the function to call.
206 * @param cArgs Number of arguments following in the ellipsis.
207 * @param ... Function arguments.
208 *
209 * @remarks See remarks on RTReqCallV.
210 */
211RTDECL(int) RTReqCall(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
212
213
214/**
215 * Allocate and queue a call request to a void function.
216 *
217 * If it's desired to poll on the completion of the request set cMillies
218 * to 0 and use RTReqWait() to check for completation. In the other case
219 * use RT_INDEFINITE_WAIT.
220 * The returned request packet must be freed using RTReqFree().
221 *
222 * @returns iprt status code.
223 * Will not return VERR_INTERRUPTED.
224 * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
225 *
226 * @param pQueue The request queue.
227 * @param ppReq Where to store the pointer to the request.
228 * This will be NULL or a valid request pointer not matter what happends.
229 * @param cMillies Number of milliseconds to wait for the request to
230 * be completed. Use RT_INDEFINITE_WAIT to only
231 * wait till it's completed.
232 * @param pfnFunction Pointer to the function to call.
233 * @param cArgs Number of arguments following in the ellipsis.
234 * @param ... Function arguments.
235 *
236 * @remarks See remarks on RTReqCallV.
237 */
238RTDECL(int) RTReqCallVoid(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
239
240
241/**
242 * Allocate and queue a call request to a void function.
243 *
244 * If it's desired to poll on the completion of the request set cMillies
245 * to 0 and use RTReqWait() to check for completation. In the other case
246 * use RT_INDEFINITE_WAIT.
247 * The returned request packet must be freed using RTReqFree().
248 *
249 * @returns iprt status code.
250 * Will not return VERR_INTERRUPTED.
251 * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
252 *
253 * @param pQueue The request queue.
254 * @param ppReq Where to store the pointer to the request.
255 * This will be NULL or a valid request pointer not matter what happends, unless fFlags
256 * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
257 * @param cMillies Number of milliseconds to wait for the request to
258 * be completed. Use RT_INDEFINITE_WAIT to only
259 * wait till it's completed.
260 * @param fFlags A combination of the RTREQFLAGS values.
261 * @param pfnFunction Pointer to the function to call.
262 * @param cArgs Number of arguments following in the ellipsis.
263 * @param ... Function arguments.
264 *
265 * @remarks See remarks on RTReqCallV.
266 */
267RTDECL(int) RTReqCallEx(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
268
269
270/**
271 * Allocate and queue a call request.
272 *
273 * If it's desired to poll on the completion of the request set cMillies
274 * to 0 and use RTReqWait() to check for completation. In the other case
275 * use RT_INDEFINITE_WAIT.
276 * The returned request packet must be freed using RTReqFree().
277 *
278 * @returns iprt status code.
279 * Will not return VERR_INTERRUPTED.
280 * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
281 *
282 * @param pQueue The request queue.
283 * @param ppReq Where to store the pointer to the request.
284 * This will be NULL or a valid request pointer not matter what happends, unless fFlags
285 * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
286 * @param cMillies Number of milliseconds to wait for the request to
287 * be completed. Use RT_INDEFINITE_WAIT to only
288 * wait till it's completed.
289 * @param fFlags A combination of the RTREQFLAGS values.
290 * @param pfnFunction Pointer to the function to call.
291 * @param cArgs Number of arguments following in the ellipsis.
292 * @param Args Variable argument vector.
293 *
294 * @remarks Caveats:
295 * - Do not pass anything which is larger than an uintptr_t.
296 * - 64-bit integers are larger than uintptr_t on 32-bit hosts.
297 * Pass integers > 32-bit by reference (pointers).
298 * - Don't use NULL since it should be the integer 0 in C++ and may
299 * therefore end up with garbage in the bits 63:32 on 64-bit
300 * hosts because 'int' is 32-bit.
301 * Use (void *)NULL or (uintptr_t)0 instead of NULL.
302 */
303RTDECL(int) RTReqCallV(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
304
305
306/**
307 * Allocates a request packet.
308 *
309 * The caller allocates a request packet, fills in the request data
310 * union and queues the request.
311 *
312 * @returns iprt status code.
313 *
314 * @param pQueue The request queue.
315 * @param ppReq Where to store the pointer to the allocated packet.
316 * @param enmType Package type.
317 */
318RTDECL(int) RTReqAlloc(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTREQTYPE enmType);
319
320
321/**
322 * Free a request packet.
323 *
324 * @returns iprt status code.
325 *
326 * @param pReq Package to free.
327 * @remark The request packet must be in allocated or completed state!
328 */
329RTDECL(int) RTReqFree(PRTREQ pReq);
330
331
332/**
333 * Queue a request.
334 *
335 * The quest must be allocated using RTReqAlloc() and contain
336 * all the required data.
337 * If it's disired to poll on the completion of the request set cMillies
338 * to 0 and use RTReqWait() to check for completation. In the other case
339 * use RT_INDEFINITE_WAIT.
340 *
341 * @returns iprt status code.
342 * Will not return VERR_INTERRUPTED.
343 * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
344 *
345 * @param pReq The request to queue.
346 * @param cMillies Number of milliseconds to wait for the request to
347 * be completed. Use RT_INDEFINITE_WAIT to only
348 * wait till it's completed.
349 */
350RTDECL(int) RTReqQueue(PRTREQ pReq, RTMSINTERVAL cMillies);
351
352
353/**
354 * Wait for a request to be completed.
355 *
356 * @returns iprt status code.
357 * Will not return VERR_INTERRUPTED.
358 * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
359 *
360 * @param pReq The request to wait for.
361 * @param cMillies Number of milliseconds to wait.
362 * Use RT_INDEFINITE_WAIT to only wait till it's completed.
363 */
364RTDECL(int) RTReqWait(PRTREQ pReq, RTMSINTERVAL cMillies);
365
366/**
367 * Checks if the queue is busy or not.
368 *
369 * The caller is responsible for dealing with any concurrent submitts.
370 *
371 * @returns true if busy, false if idle.
372 * @param pQueue The queue.
373 */
374RTDECL(bool) RTReqIsBusy(PRTREQQUEUE pQueue);
375
376#endif /* IN_RING3 */
377
378
379/** @} */
380
381RT_C_DECLS_END
382
383#endif
384
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