req.h@ 88810

Last change on this file since 88810 was 88810, checked in by vboxsync, 4 years ago
IPRT/RTReqPool: Added RTREQPOOLCFGVAR_THREAD_FLAGS so we can supply RTTHREADFLAGS_COM_MTA or similar to RTThreadCreate for the pool. bugref:9890
Property eol-style set to `native` Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 24.0 KB

Line
1	/** @file
2	* IPRT - Request Queue & Pool.
3	*/
4
5	/*
6	* Copyright (C) 2006-2020 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	* Retains a 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 RTTHREADFLAGS mask for the worker threads (not waitable). */
335	RTREQPOOLCFGVAR_THREAD_FLAGS,
336	/** The minimum number of threads to keep handy once spawned. */
337	RTREQPOOLCFGVAR_MIN_THREADS,
338	/** The maximum number of thread to start. */
339	RTREQPOOLCFGVAR_MAX_THREADS,
340	/** The minimum number of milliseconds a worker thread needs to be idle
341	* before we consider shutting it down. The other shutdown criteria
342	* being set by RTREQPOOLCFGVAR_MIN_THREADS. The value
343	* RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
344	RTREQPOOLCFGVAR_MS_MIN_IDLE,
345	/** The sleep period, in milliseoncds, to employ when idling. The value
346	* RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
347	RTREQPOOLCFGVAR_MS_IDLE_SLEEP,
348	/** The number of threads at which to start pushing back. The value
349	* UINT64_MAX is an alias for the current upper thread count limit, i.e.
350	* disabling push back. The value 0 (zero) is an alias for the current
351	* lower thread count, a good value to start pushing back at. The value
352	* must otherwise be within */
353	RTREQPOOLCFGVAR_PUSH_BACK_THRESHOLD,
354	/** The minimum push back time in milliseconds. */
355	RTREQPOOLCFGVAR_PUSH_BACK_MIN_MS,
356	/** The maximum push back time in milliseconds. */
357	RTREQPOOLCFGVAR_PUSH_BACK_MAX_MS,
358	/** The maximum number of free requests to keep handy for recycling. */
359	RTREQPOOLCFGVAR_MAX_FREE_REQUESTS,
360	/** The end of the range of valid config variables. */
361	RTREQPOOLCFGVAR_END,
362	/** Blow the type up to 32-bits. */
363	RTREQPOOLCFGVAR_32BIT_HACK = 0x7fffffff
364	} RTREQPOOLCFGVAR;
365
366
367	/**
368	* Sets a config variable for a request thread pool.
369	*
370	* @returns IPRT status code.
371	* @param hPool The pool handle.
372	* @param enmVar The variable to set.
373	* @param uValue The new value.
374	*/
375	RTDECL(int) RTReqPoolSetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar, uint64_t uValue);
376
377	/**
378	* Gets a config variable for a request thread pool.
379	*
380	* @returns The value, UINT64_MAX on invalid parameters.
381	* @param hPool The pool handle.
382	* @param enmVar The variable to query.
383	*/
384	RTDECL(uint64_t) RTReqPoolGetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar);
385
386	/**
387	* Request thread pool statistics value names.
388	*/
389	typedef enum RTREQPOOLSTAT
390	{
391	/** The invalid zero value, as per tradition. */
392	RTREQPOOLSTAT_INVALID = 0,
393	/** The current number of worker threads. */
394	RTREQPOOLSTAT_THREADS,
395	/** The number of threads that have been created. */
396	RTREQPOOLSTAT_THREADS_CREATED,
397	/** The total number of requests that have been processed. */
398	RTREQPOOLSTAT_REQUESTS_PROCESSED,
399	/** The total number of requests that have been submitted. */
400	RTREQPOOLSTAT_REQUESTS_SUBMITTED,
401	/** the current number of pending (waiting) requests. */
402	RTREQPOOLSTAT_REQUESTS_PENDING,
403	/** The current number of active (executing) requests. */
404	RTREQPOOLSTAT_REQUESTS_ACTIVE,
405	/** The current number of free (recycled) requests. */
406	RTREQPOOLSTAT_REQUESTS_FREE,
407	/** Total time the requests took to process. */
408	RTREQPOOLSTAT_NS_TOTAL_REQ_PROCESSING,
409	/** Total time the requests had to wait in the queue before being
410	* scheduled. */
411	RTREQPOOLSTAT_NS_TOTAL_REQ_QUEUED,
412	/** Average time the requests took to process. */
413	RTREQPOOLSTAT_NS_AVERAGE_REQ_PROCESSING,
414	/** Average time the requests had to wait in the queue before being
415	* scheduled. */
416	RTREQPOOLSTAT_NS_AVERAGE_REQ_QUEUED,
417	/** The end of the valid statistics value names. */
418	RTREQPOOLSTAT_END,
419	/** Blow the type up to 32-bit. */
420	RTREQPOOLSTAT_32BIT_HACK = 0x7fffffff
421	} RTREQPOOLSTAT;
422
423	/**
424	* Reads a statistics value from the request thread pool.
425	*
426	* @returns The value, UINT64_MAX if an invalid parameter was given.
427	* @param hPool The request thread pool handle.
428	* @param enmStat The statistics value to get.
429	*/
430	RTDECL(uint64_t) RTReqPoolGetStat(RTREQPOOL hPool, RTREQPOOLSTAT enmStat);
431
432	/**
433	* Allocates a request packet.
434	*
435	* This is mostly for internal use, please use the convenience methods.
436	*
437	* @returns IPRT status code.
438	*
439	* @param hPool The request thread pool handle.
440	* @param enmType Package type.
441	* @param phReq Where to store the handle to the new request.
442	*/
443	RTDECL(int) RTReqPoolAlloc(RTREQPOOL hPool, RTREQTYPE enmType, PRTREQ *phReq);
444
445	/**
446	* Calls a function on a worker thread.
447	*
448	* @returns IPRT status code.
449	* @param hPool The request thread pool handle.
450	* @param cMillies The number of milliseconds to wait for the request
451	* to be processed.
452	* @param phReq Where to return the request. Can be NULL if the
453	* RTREQFLAGS_NO_WAIT flag is used.
454	* @param fFlags A combination of RTREQFLAGS values.
455	* @param pfnFunction The function to be called. Must be declared by a
456	* DECL macro because of calling conventions.
457	* @param cArgs The number of arguments in the ellipsis.
458	* @param ... Arguments.
459	*
460	* @remarks The function better avoid taking uint64_t and structs as part of the
461	* arguments (use pointers to these instead). In general anything
462	* that's larger than an uintptr_t is problematic.
463	*/
464	RTDECL(int) RTReqPoolCallEx(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
465
466
467	/**
468	* Calls a function on a worker thread.
469	*
470	* @returns IPRT status code.
471	* @param hPool The request thread pool handle.
472	* @param cMillies The number of milliseconds to wait for the request
473	* to be processed.
474	* @param phReq Where to return the request. Can be NULL if the
475	* RTREQFLAGS_NO_WAIT flag is used.
476	* @param fFlags A combination of RTREQFLAGS values.
477	* @param pfnFunction The function to be called. Must be declared by a
478	* DECL macro because of calling conventions.
479	* @param cArgs The number of arguments in the variable argument
480	* list.
481	* @param va Arguments.
482	* @remarks See remarks on RTReqPoolCallEx.
483	*/
484	RTDECL(int) RTReqPoolCallExV(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list va);
485
486	/**
487	* Calls a function on a worker thread, wait for it to return.
488	*
489	* @returns IPRT status code returned by @a pfnFunction or request pool error.
490	* @param hPool The request thread pool handle.
491	* @param pfnFunction The function to be called. Must be declared by a
492	* DECL macro because of calling conventions. The
493	* function must return an int value compatible with
494	* the IPRT status code convention.
495	* @param cArgs The number of arguments in the elipsis.
496	* @param ... Arguments.
497	* @remarks See remarks on RTReqPoolCallEx.
498	*/
499	RTDECL(int) RTReqPoolCallWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
500
501	/**
502	* Calls a function on a worker thread, don't wait for it to return.
503	*
504	* @returns IPRT status code.
505	* @param hPool The request thread pool handle.
506	* @param pfnFunction The function to be called. Must be declared by a
507	* DECL macro because of calling conventions. The
508	* function should return an int value compatible with
509	* the IPRT status code convention, thought it's not
510	* all that important as it's thrown away.
511	* @param cArgs The number of arguments in the elipsis.
512	* @param ... Arguments.
513	* @remarks See remarks on RTReqPoolCallEx.
514	*/
515	RTDECL(int) RTReqPoolCallNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
516
517	/**
518	* Calls a void function on a worker thread.
519	*
520	* @returns IPRT status code.
521	* @param hPool The request thread pool handle.
522	* @param pfnFunction The function to be called. Must be declared by a
523	* DECL macro because of calling conventions. The
524	* function is taken to return void.
525	* @param cArgs The number of arguments in the elipsis.
526	* @param ... Arguments.
527	* @remarks See remarks on RTReqPoolCallEx.
528	*/
529	RTDECL(int) RTReqPoolCallVoidWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
530
531	/**
532	* Call a void function on a worker thread, don't wait for it to return.
533	*
534	* @returns IPRT status code.
535	* @param hPool The request thread pool handle.
536	* @param pfnFunction The function to be called. Must be declared by a
537	* DECL macro because of calling conventions. The
538	* function is taken to return void.
539	* @param cArgs The number of arguments in the elipsis.
540	* @param ... Arguments.
541	* @remarks See remarks on RTReqPoolCallEx.
542	*/
543	RTDECL(int) RTReqPoolCallVoidNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
544
545
546	/**
547	* Retains a reference to a request.
548	*
549	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
550	* @param hReq The request handle.
551	*/
552	RTDECL(uint32_t) RTReqRetain(PRTREQ hReq);
553
554	/**
555	* Releases a reference to the request.
556	*
557	* When the reference count reaches zero, the request will be pooled for reuse.
558	*
559	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
560	* @param hReq Package to release.
561	*/
562	RTDECL(uint32_t) RTReqRelease(PRTREQ hReq);
563
564	/**
565	* Queues a request.
566	*
567	* The request must be allocated using RTReqQueueAlloc() or RTReqPoolAlloc() and
568	* contain all the required data.
569	*
570	* If it's desired to poll on the completion of the request set cMillies
571	* to 0 and use RTReqWait() to check for completion. In the other case
572	* use RT_INDEFINITE_WAIT.
573	*
574	* @returns IPRT status code.
575	* Will not return VERR_INTERRUPTED.
576	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
577	*
578	* @param pReq The request to queue.
579	* @param cMillies Number of milliseconds to wait for the request to
580	* be completed. Use RT_INDEFINITE_WAIT to only
581	* wait till it's completed.
582	*/
583	RTDECL(int) RTReqSubmit(PRTREQ pReq, RTMSINTERVAL cMillies);
584
585
586	/**
587	* Waits for a request to be completed.
588	*
589	* @returns IPRT status code.
590	* Will not return VERR_INTERRUPTED.
591	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
592	*
593	* @param pReq The request to wait for.
594	* @param cMillies Number of milliseconds to wait.
595	* Use RT_INDEFINITE_WAIT to only wait till it's completed.
596	*/
597	RTDECL(int) RTReqWait(PRTREQ pReq, RTMSINTERVAL cMillies);
598
599	/**
600	* Gets the status of the request.
601	*
602	* @returns IPRT status code.
603	*
604	* @param pReq The request to get the status for.
605	*/
606	RTDECL(int) RTReqGetStatus(PRTREQ pReq);
607
608	#endif /* IN_RING3 */
609
610
611	/** @} */
612
613	RT_C_DECLS_END
614
615	#endif /* !IPRT_INCLUDED_req_h */
616

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

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

Download in other formats: