VirtualBox

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

Last change on this file since 8155 was 8155, checked in by vboxsync, 16 years ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use