VirtualBox

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

Last change on this file since 3251 was 2981, checked in by vboxsync, 17 years ago

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