req.h@ 81025

Last change on this file since 81025 was 76585, checked in by vboxsync, 6 years ago
*: scm --fix-header-guard-endif
Property eol-style set to `native` Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 23.9 KB

Line
1	/** @file
2	* IPRT - Request Queue & Pool.
3	*/
4
5	/*
6	* Copyright (C) 2006-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_req_h
27	#define IPRT_INCLUDED_req_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/cdefs.h>
33	#include <iprt/types.h>
34
35	#include <iprt/stdarg.h>
36
37	RT_C_DECLS_BEGIN
38
39	/** @defgroup grp_rt_req RTReq - Request Queue & Pool.
40	* @ingroup grp_rt
41	* @{
42	*/
43
44	/** Request queue handle. */
45	typedef struct RTREQQUEUEINT *RTREQQUEUE;
46	/** Pointer to a request queue handle. */
47	typedef RTREQQUEUE *PRTREQQUEUE;
48	/** NIL request queue handle. */
49	#define NIL_RTREQQUEUE ((RTREQQUEUE)0)
50
51	/** Request thread pool handle. */
52	typedef struct RTREQPOOLINT *RTREQPOOL;
53	/** Poiner to a request thread pool handle. */
54	typedef RTREQPOOL *PRTREQPOOL;
55	/** NIL request pool handle. */
56	#define NIL_RTREQPOOL ((RTREQPOOL)0)
57
58
59	/**
60	* Request type.
61	*/
62	typedef enum RTREQTYPE
63	{
64	/** Invalid request. */
65	RTREQTYPE_INVALID = 0,
66	/** RT: Internal. */
67	RTREQTYPE_INTERNAL,
68	/** Maximum request type (exclusive). Used for validation. */
69	RTREQTYPE_MAX
70	} RTREQTYPE;
71
72	/**
73	* Request flags.
74	*/
75	typedef enum RTREQFLAGS
76	{
77	/** The request returns a iprt status code. */
78	RTREQFLAGS_IPRT_STATUS = 0,
79	/** The request is a void request and have no status code. */
80	RTREQFLAGS_VOID = 1,
81	/** Return type mask. */
82	RTREQFLAGS_RETURN_MASK = 1,
83	/** Caller does not wait on the packet, Queue process thread will free it. */
84	RTREQFLAGS_NO_WAIT = 2
85	} RTREQFLAGS;
86
87
88	/** A request packet. */
89	typedef struct RTREQ RTREQ;
90	/** Pointer to an RT request packet. */
91	typedef RTREQ *PRTREQ;
92	/** Nil request handle. */
93	#define NIL_RTREQ ((PRTREQ)0)
94
95
96	#ifdef IN_RING3
97
98	/**
99	* Create a request packet queue
100	*
101	* @returns iprt status code.
102	* @param phQueue Where to store the request queue handle.
103	*/
104	RTDECL(int) RTReqQueueCreate(PRTREQQUEUE phQueue);
105
106	/**
107	* Destroy a request packet queue
108	*
109	* @returns iprt status code.
110	* @param hQueue The request queue.
111	*/
112	RTDECL(int) RTReqQueueDestroy(RTREQQUEUE hQueue);
113
114	/**
115	* Process one or more request packets
116	*
117	* @returns iprt status code. Any non-VINF_SUCCESS returns from request
118	* processing is immediately propagated to the caller.
119	* @retval VERR_TIMEOUT if @a cMillies was reached without the packet being
120	* added.
121	* @retval VERR_INVALID_HANDLE if @a hQueue not a valid queue handle.
122	*
123	* @param hQueue The request queue.
124	* @param cMillies Max number of milliseconds to wait for a pending
125	* request. This is not adjusted down before another
126	* wait, so the function may end up waiting for much
127	* longer than the given amount if there are requests
128	* trickling in at a rate slightly higher than the
129	* timeout.
130	*
131	* Use RT_INDEFINITE_WAIT to process requests until a
132	* non-VINF_SUCCESS return code is encountered.
133	*
134	* @remarks The function may repeatedly try wait for @a cMillies on new
135	* requests if requests arrive before it times out.
136	*/
137	RTDECL(int) RTReqQueueProcess(RTREQQUEUE hQueue, RTMSINTERVAL cMillies);
138
139	/**
140	* Allocate and queue a call request.
141	*
142	* If it's desired to poll on the completion of the request set cMillies
143	* to 0 and use RTReqWait() to check for completion. In the other case
144	* use RT_INDEFINITE_WAIT.
145	* The returned request packet must be freed using RTReqRelease().
146	*
147	* @returns iprt statuscode.
148	* Will not return VERR_INTERRUPTED.
149	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
150	*
151	* @param hQueue The request queue.
152	* @param ppReq Where to store the pointer to the request.
153	* This will be NULL or a valid request pointer not matter what happens.
154	* @param cMillies Number of milliseconds to wait for the request to
155	* be completed. Use RT_INDEFINITE_WAIT to only
156	* wait till it's completed.
157	* @param pfnFunction Pointer to the function to call.
158	* @param cArgs Number of arguments following in the ellipsis.
159	* @param ... Function arguments.
160	*
161	* @remarks See remarks on RTReqQueueCallV.
162	*/
163	RTDECL(int) RTReqQueueCall(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
164
165	/**
166	* Allocate and queue a call request to a void function.
167	*
168	* If it's desired to poll on the completion of the request set cMillies
169	* to 0 and use RTReqWait() to check for completion. In the other case
170	* use RT_INDEFINITE_WAIT.
171	* The returned request packet must be freed using RTReqRelease().
172	*
173	* @returns iprt status code.
174	* Will not return VERR_INTERRUPTED.
175	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
176	*
177	* @param hQueue The request queue.
178	* @param ppReq Where to store the pointer to the request.
179	* This will be NULL or a valid request pointer not matter what happens.
180	* @param cMillies Number of milliseconds to wait for the request to
181	* be completed. Use RT_INDEFINITE_WAIT to only
182	* wait till it's completed.
183	* @param pfnFunction Pointer to the function to call.
184	* @param cArgs Number of arguments following in the ellipsis.
185	* @param ... Function arguments.
186	*
187	* @remarks See remarks on RTReqQueueCallV.
188	*/
189	RTDECL(int) RTReqQueueCallVoid(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
190
191	/**
192	* Allocate and queue a call request to a void function.
193	*
194	* If it's desired to poll on the completion of the request set cMillies
195	* to 0 and use RTReqWait() to check for completion. In the other case
196	* use RT_INDEFINITE_WAIT.
197	* The returned request packet must be freed using RTReqRelease().
198	*
199	* @returns iprt status code.
200	* Will not return VERR_INTERRUPTED.
201	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
202	*
203	* @param hQueue The request queue.
204	* @param ppReq Where to store the pointer to the request.
205	* This will be NULL or a valid request pointer not matter what happens, unless fFlags
206	* contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
207	* @param cMillies Number of milliseconds to wait for the request to
208	* be completed. Use RT_INDEFINITE_WAIT to only
209	* wait till it's completed.
210	* @param fFlags A combination of the RTREQFLAGS values.
211	* @param pfnFunction Pointer to the function to call.
212	* @param cArgs Number of arguments following in the ellipsis.
213	* @param ... Function arguments.
214	*
215	* @remarks See remarks on RTReqQueueCallV.
216	*/
217	RTDECL(int) RTReqQueueCallEx(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
218
219	/**
220	* Allocate and queue a call request.
221	*
222	* If it's desired to poll on the completion of the request set cMillies
223	* to 0 and use RTReqWait() to check for completion. In the other case
224	* use RT_INDEFINITE_WAIT.
225	* The returned request packet must be freed using RTReqRelease().
226	*
227	* @returns iprt status code.
228	* Will not return VERR_INTERRUPTED.
229	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
230	*
231	* @param hQueue The request queue.
232	* @param ppReq Where to store the pointer to the request.
233	* This will be NULL or a valid request pointer not matter what happens, unless fFlags
234	* contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
235	* @param cMillies Number of milliseconds to wait for the request to
236	* be completed. Use RT_INDEFINITE_WAIT to only
237	* wait till it's completed.
238	* @param fFlags A combination of the RTREQFLAGS values.
239	* @param pfnFunction Pointer to the function to call.
240	* @param cArgs Number of arguments following in the ellipsis.
241	* @param Args Variable argument vector.
242	*
243	* @remarks Caveats:
244	* - Do not pass anything which is larger than an uintptr_t.
245	* - 64-bit integers are larger than uintptr_t on 32-bit hosts.
246	* Pass integers > 32-bit by reference (pointers).
247	* - Don't use NULL since it should be the integer 0 in C++ and may
248	* therefore end up with garbage in the bits 63:32 on 64-bit
249	* hosts because 'int' is 32-bit.
250	* Use (void *)NULL or (uintptr_t)0 instead of NULL.
251	*/
252	RTDECL(int) RTReqQueueCallV(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
253
254	/**
255	* Checks if the queue is busy or not.
256	*
257	* The caller is responsible for dealing with any concurrent submitts.
258	*
259	* @returns true if busy, false if idle.
260	* @param hQueue The queue.
261	*/
262	RTDECL(bool) RTReqQueueIsBusy(RTREQQUEUE hQueue);
263
264	/**
265	* Allocates a request packet.
266	*
267	* The caller allocates a request packet, fills in the request data
268	* union and queues the request.
269	*
270	* @returns iprt status code.
271	*
272	* @param hQueue The request queue.
273	* @param enmType Package type.
274	* @param phReq Where to store the handle to the new request.
275	*/
276	RTDECL(int) RTReqQueueAlloc(RTREQQUEUE hQueue, RTREQTYPE enmType, PRTREQ *phReq);
277
278
279	/**
280	* Creates a request thread pool.
281	*
282	* The core configuration is given as parameters, finer pool tuning can be
283	* achieved via RTReqPoolSetCfgVar.
284	*
285	* @returns IPRT status code.
286	* @param cMaxThreads The maximum number of worker threads.
287	* UINT32_MAX is an alias for the highest
288	* allowed thread count.
289	* @param cMsMinIdle The number of milliseconds a worker
290	* thread needs to be idle before it is
291	* considered for shutdown. The value
292	* RT_INDEFINITE_WAIT disables automatic
293	* idle thread shutdown.
294	* @param cThreadsPushBackThreshold At which worker thread count the push
295	* back should kick in.
296	* @param cMsMaxPushBack The max number of milliseconds to push
297	* back a submitter. UINT32_MAX is an
298	* alias for the highest allowed push back.
299	* @param pszName The pool name. Keep it short as it is
300	* used for naming worker threads.
301	* @param phPool Where to return the pool handle.
302	*/
303	RTDECL(int) RTReqPoolCreate(uint32_t cMaxThreads, RTMSINTERVAL cMsMinIdle,
304	uint32_t cThreadsPushBackThreshold, uint32_t cMsMaxPushBack,
305	const char *pszName, PRTREQPOOL phPool);
306
307	/**
308	* Retainsa reference to a request thread pool.
309	*
310	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
311	* @param hPool The request thread pool handle.
312	*/
313	RTDECL(uint32_t) RTReqPoolRetain(RTREQPOOL hPool);
314
315	/**
316	* Releases a reference to the request thread pool.
317	*
318	* When the reference count reaches zero, the request will be pooled for reuse.
319	*
320	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
321	* @param hPool The request thread pool handle.
322	*/
323	RTDECL(uint32_t) RTReqPoolRelease(RTREQPOOL hPool);
324
325	/**
326	* Request thread pool configuration variable.
327	*/
328	typedef enum RTREQPOOLCFGVAR
329	{
330	/** Invalid zero value. */
331	RTREQPOOLCFGVAR_INVALID = 0,
332	/** The desired RTTHREADTYPE of the worker threads. */
333	RTREQPOOLCFGVAR_THREAD_TYPE,
334	/** The minimum number of threads to keep handy once spawned. */
335	RTREQPOOLCFGVAR_MIN_THREADS,
336	/** The maximum number of thread to start. */
337	RTREQPOOLCFGVAR_MAX_THREADS,
338	/** The minimum number of milliseconds a worker thread needs to be idle
339	* before we consider shutting it down. The other shutdown criteria
340	* being set by RTREQPOOLCFGVAR_MIN_THREADS. The value
341	* RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
342	RTREQPOOLCFGVAR_MS_MIN_IDLE,
343	/** The sleep period, in milliseoncds, to employ when idling. The value
344	* RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
345	RTREQPOOLCFGVAR_MS_IDLE_SLEEP,
346	/** The number of threads at which to start pushing back. The value
347	* UINT64_MAX is an alias for the current upper thread count limit, i.e.
348	* disabling push back. The value 0 (zero) is an alias for the current
349	* lower thread count, a good value to start pushing back at. The value
350	* must otherwise be within */
351	RTREQPOOLCFGVAR_PUSH_BACK_THRESHOLD,
352	/** The minimum push back time in milliseconds. */
353	RTREQPOOLCFGVAR_PUSH_BACK_MIN_MS,
354	/** The maximum push back time in milliseconds. */
355	RTREQPOOLCFGVAR_PUSH_BACK_MAX_MS,
356	/** The maximum number of free requests to keep handy for recycling. */
357	RTREQPOOLCFGVAR_MAX_FREE_REQUESTS,
358	/** The end of the range of valid config variables. */
359	RTREQPOOLCFGVAR_END,
360	/** Blow the type up to 32-bits. */
361	RTREQPOOLCFGVAR_32BIT_HACK = 0x7fffffff
362	} RTREQPOOLCFGVAR;
363
364
365	/**
366	* Sets a config variable for a request thread pool.
367	*
368	* @returns IPRT status code.
369	* @param hPool The pool handle.
370	* @param enmVar The variable to set.
371	* @param uValue The new value.
372	*/
373	RTDECL(int) RTReqPoolSetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar, uint64_t uValue);
374
375	/**
376	* Gets a config variable for a request thread pool.
377	*
378	* @returns The value, UINT64_MAX on invalid parameters.
379	* @param hPool The pool handle.
380	* @param enmVar The variable to query.
381	*/
382	RTDECL(uint64_t) RTReqPoolGetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar);
383
384	/**
385	* Request thread pool statistics value names.
386	*/
387	typedef enum RTREQPOOLSTAT
388	{
389	/** The invalid zero value, as per tradition. */
390	RTREQPOOLSTAT_INVALID = 0,
391	/** The current number of worker threads. */
392	RTREQPOOLSTAT_THREADS,
393	/** The number of threads that have been created. */
394	RTREQPOOLSTAT_THREADS_CREATED,
395	/** The total number of requests that have been processed. */
396	RTREQPOOLSTAT_REQUESTS_PROCESSED,
397	/** The total number of requests that have been submitted. */
398	RTREQPOOLSTAT_REQUESTS_SUBMITTED,
399	/** the current number of pending (waiting) requests. */
400	RTREQPOOLSTAT_REQUESTS_PENDING,
401	/** The current number of active (executing) requests. */
402	RTREQPOOLSTAT_REQUESTS_ACTIVE,
403	/** The current number of free (recycled) requests. */
404	RTREQPOOLSTAT_REQUESTS_FREE,
405	/** Total time the requests took to process. */
406	RTREQPOOLSTAT_NS_TOTAL_REQ_PROCESSING,
407	/** Total time the requests had to wait in the queue before being
408	* scheduled. */
409	RTREQPOOLSTAT_NS_TOTAL_REQ_QUEUED,
410	/** Average time the requests took to process. */
411	RTREQPOOLSTAT_NS_AVERAGE_REQ_PROCESSING,
412	/** Average time the requests had to wait in the queue before being
413	* scheduled. */
414	RTREQPOOLSTAT_NS_AVERAGE_REQ_QUEUED,
415	/** The end of the valid statistics value names. */
416	RTREQPOOLSTAT_END,
417	/** Blow the type up to 32-bit. */
418	RTREQPOOLSTAT_32BIT_HACK = 0x7fffffff
419	} RTREQPOOLSTAT;
420
421	/**
422	* Read a statistics value from the request thread pool.
423	*
424	* @returns The value, UINT64_MAX if an invalid parameter was given.
425	* @param hPool The request thread pool handle.
426	* @param enmStat The statistics value to get.
427	*/
428	RTDECL(uint64_t) RTReqPoolGetStat(RTREQPOOL hPool, RTREQPOOLSTAT enmStat);
429
430	/**
431	* Allocates a request packet.
432	*
433	* This is mostly for internal use, please use the convenience methods.
434	*
435	* @returns iprt status code.
436	*
437	* @param hPool The request thread pool handle.
438	* @param enmType Package type.
439	* @param phReq Where to store the handle to the new request.
440	*/
441	RTDECL(int) RTReqPoolAlloc(RTREQPOOL hPool, RTREQTYPE enmType, PRTREQ *phReq);
442
443	/**
444	* Call a function on a worker thread.
445	*
446	* @returns IPRT status code.
447	* @param hPool The request thread pool handle.
448	* @param cMillies The number of milliseconds to wait for the request
449	* to be processed.
450	* @param phReq Where to return the request. Can be NULL if the
451	* RTREQFLAGS_NO_WAIT flag is used.
452	* @param fFlags A combination of RTREQFLAGS values.
453	* @param pfnFunction The function to be called. Must be declared by a
454	* DECL macro because of calling conventions.
455	* @param cArgs The number of arguments in the ellipsis.
456	* @param ... Arguments.
457	*
458	* @remarks The function better avoid taking uint64_t and structs as part of the
459	* arguments (use pointers to these instead). In general anything
460	* that's larger than an uintptr_t is problematic.
461	*/
462	RTDECL(int) RTReqPoolCallEx( RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
463
464
465	/**
466	* Call a function on a worker thread.
467	*
468	* @returns IPRT status code.
469	* @param hPool The request thread pool handle.
470	* @param cMillies The number of milliseconds to wait for the request
471	* to be processed.
472	* @param phReq Where to return the request. Can be NULL if the
473	* RTREQFLAGS_NO_WAIT flag is used.
474	* @param fFlags A combination of RTREQFLAGS values.
475	* @param pfnFunction The function to be called. Must be declared by a
476	* DECL macro because of calling conventions.
477	* @param cArgs The number of arguments in the variable argument
478	* list.
479	* @param va Arguments.
480	* @remarks See remarks on RTReqPoolCallEx.
481	*/
482	RTDECL(int) RTReqPoolCallExV(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list va);
483
484	/**
485	* Call a function on a worker thread, wait for it to return.
486	*
487	* @returns IPRT status code returned by @a pfnFunction or request pool error.
488	* @param hPool The request thread pool handle.
489	* @param pfnFunction The function to be called. Must be declared by a
490	* DECL macro because of calling conventions. The
491	* function must return an int value compatible with
492	* the IPRT status code convention.
493	* @param cArgs The number of arguments in the elipsis.
494	* @param ... Arguments.
495	* @remarks See remarks on RTReqPoolCallEx.
496	*/
497	RTDECL(int) RTReqPoolCallWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
498
499	/**
500	* Call a function on a worker thread, don't wait for it to return.
501	*
502	* @returns IPRT status code.
503	* @param hPool The request thread pool handle.
504	* @param pfnFunction The function to be called. Must be declared by a
505	* DECL macro because of calling conventions. The
506	* function should return an int value compatible with
507	* the IPRT status code convention, thought it's not
508	* all that important as it's thrown away.
509	* @param cArgs The number of arguments in the elipsis.
510	* @param ... Arguments.
511	* @remarks See remarks on RTReqPoolCallEx.
512	*/
513	RTDECL(int) RTReqPoolCallNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
514
515	/**
516	* Call a void function on a worker thread.
517	*
518	* @returns IPRT status code.
519	* @param hPool The request thread pool handle.
520	* @param pfnFunction The function to be called. Must be declared by a
521	* DECL macro because of calling conventions. The
522	* function is taken to return void.
523	* @param cArgs The number of arguments in the elipsis.
524	* @param ... Arguments.
525	* @remarks See remarks on RTReqPoolCallEx.
526	*/
527	RTDECL(int) RTReqPoolCallVoidWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
528
529	/**
530	* Call a void function on a worker thread, don't wait for it to return.
531	*
532	* @returns IPRT status code.
533	* @param hPool The request thread pool handle.
534	* @param pfnFunction The function to be called. Must be declared by a
535	* DECL macro because of calling conventions. The
536	* function is taken to return void.
537	* @param cArgs The number of arguments in the elipsis.
538	* @param ... Arguments.
539	* @remarks See remarks on RTReqPoolCallEx.
540	*/
541	RTDECL(int) RTReqPoolCallVoidNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
542
543
544	/**
545	* Retainsa reference to a request.
546	*
547	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
548	* @param hReq The request handle.
549	*/
550	RTDECL(uint32_t) RTReqRetain(PRTREQ hReq);
551
552	/**
553	* Releases a reference to the request.
554	*
555	* When the reference count reaches zero, the request will be pooled for reuse.
556	*
557	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
558	* @param hReq Package to release.
559	*/
560	RTDECL(uint32_t) RTReqRelease(PRTREQ hReq);
561
562	/**
563	* Queue a request.
564	*
565	* The quest must be allocated using RTReqQueueAlloc() or RTReqPoolAlloc() and
566	* contain all the required data.
567	*
568	* If it's desired to poll on the completion of the request set cMillies
569	* to 0 and use RTReqWait() to check for completion. In the other case
570	* use RT_INDEFINITE_WAIT.
571	*
572	* @returns iprt status code.
573	* Will not return VERR_INTERRUPTED.
574	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
575	*
576	* @param pReq The request to queue.
577	* @param cMillies Number of milliseconds to wait for the request to
578	* be completed. Use RT_INDEFINITE_WAIT to only
579	* wait till it's completed.
580	*/
581	RTDECL(int) RTReqSubmit(PRTREQ pReq, RTMSINTERVAL cMillies);
582
583
584	/**
585	* Wait for a request to be completed.
586	*
587	* @returns iprt status code.
588	* Will not return VERR_INTERRUPTED.
589	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
590	*
591	* @param pReq The request to wait for.
592	* @param cMillies Number of milliseconds to wait.
593	* Use RT_INDEFINITE_WAIT to only wait till it's completed.
594	*/
595	RTDECL(int) RTReqWait(PRTREQ pReq, RTMSINTERVAL cMillies);
596
597	/**
598	* Get the status of the request.
599	*
600	* @returns Status code in the IPRT tradition.
601	*
602	* @param pReq The request.
603	*/
604	RTDECL(int) RTReqGetStatus(PRTREQ pReq);
605
606	#endif /* IN_RING3 */
607
608
609	/** @} */
610
611	RT_C_DECLS_END
612
613	#endif /* !IPRT_INCLUDED_req_h */
614

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: