req.h@ 91991

Last change on this file since 91991 was 88813, checked in by vboxsync, 4 years ago
IPRT/RTReq: Added a RTReqCancel function. Changed the behavior of the RTREQFLAGS_NO_WAIT to optionally return the request handle rather than obstinately returning NIL even when the phReq parameter is not NULL. This makes the usage clearer and allows canceling NO_WAIT requests. (Needed in DrvAudio.) 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.6 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. */
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. Optional
205	* when RTREQFLAGS_NO_WAIT is used.
206	* This variable will be set to NIL or a valid request
207	* handle not matter what happens.
208	* @param cMillies Number of milliseconds to wait for the request to
209	* be completed. Use RT_INDEFINITE_WAIT to only
210	* wait till it's completed.
211	* @param fFlags A combination of the RTREQFLAGS values.
212	* @param pfnFunction Pointer to the function to call.
213	* @param cArgs Number of arguments following in the ellipsis.
214	* @param ... Function arguments.
215	*
216	* @remarks See remarks on RTReqQueueCallV.
217	*/
218	RTDECL(int) RTReqQueueCallEx(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
219
220	/**
221	* Allocate and queue a call request.
222	*
223	* If it's desired to poll on the completion of the request set cMillies
224	* to 0 and use RTReqWait() to check for completion. In the other case
225	* use RT_INDEFINITE_WAIT.
226	* The returned request packet must be freed using RTReqRelease().
227	*
228	* @returns IPRT status code.
229	* Will not return VERR_INTERRUPTED.
230	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
231	*
232	* @param hQueue The request queue.
233	* @param ppReq Where to store the pointer to the request. Optional
234	* when RTREQFLAGS_NO_WAIT is used.
235	* This variable will be set to NIL or a valid request
236	* handle not matter what happens.
237	* @param cMillies Number of milliseconds to wait for the request to
238	* be completed. Use RT_INDEFINITE_WAIT to only
239	* wait till it's completed.
240	* @param fFlags A combination of the RTREQFLAGS values.
241	* @param pfnFunction Pointer to the function to call.
242	* @param cArgs Number of arguments following in the ellipsis.
243	* @param Args Variable argument vector.
244	*
245	* @remarks Caveats:
246	* - Do not pass anything which is larger than an uintptr_t.
247	* - 64-bit integers are larger than uintptr_t on 32-bit hosts.
248	* Pass integers > 32-bit by reference (pointers).
249	* - Don't use NULL since it should be the integer 0 in C++ and may
250	* therefore end up with garbage in the bits 63:32 on 64-bit
251	* hosts because 'int' is 32-bit.
252	* Use (void *)NULL or (uintptr_t)0 instead of NULL.
253	*/
254	RTDECL(int) RTReqQueueCallV(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
255
256	/**
257	* Checks if the queue is busy or not.
258	*
259	* The caller is responsible for dealing with any concurrent submitts.
260	*
261	* @returns true if busy, false if idle.
262	* @param hQueue The queue.
263	*/
264	RTDECL(bool) RTReqQueueIsBusy(RTREQQUEUE hQueue);
265
266	/**
267	* Allocates a request packet.
268	*
269	* The caller allocates a request packet, fills in the request data
270	* union and queues the request.
271	*
272	* @returns IPRT status code.
273	*
274	* @param hQueue The request queue.
275	* @param enmType Package type.
276	* @param phReq Where to store the handle to the new request.
277	*/
278	RTDECL(int) RTReqQueueAlloc(RTREQQUEUE hQueue, RTREQTYPE enmType, PRTREQ *phReq);
279
280
281	/**
282	* Creates a request thread pool.
283	*
284	* The core configuration is given as parameters, finer pool tuning can be
285	* achieved via RTReqPoolSetCfgVar.
286	*
287	* @returns IPRT status code.
288	* @param cMaxThreads The maximum number of worker threads.
289	* UINT32_MAX is an alias for the highest
290	* allowed thread count.
291	* @param cMsMinIdle The number of milliseconds a worker
292	* thread needs to be idle before it is
293	* considered for shutdown. The value
294	* RT_INDEFINITE_WAIT disables automatic
295	* idle thread shutdown.
296	* @param cThreadsPushBackThreshold At which worker thread count the push
297	* back should kick in.
298	* @param cMsMaxPushBack The max number of milliseconds to push
299	* back a submitter. UINT32_MAX is an
300	* alias for the highest allowed push back.
301	* @param pszName The pool name. Keep it short as it is
302	* used for naming worker threads.
303	* @param phPool Where to return the pool handle.
304	*/
305	RTDECL(int) RTReqPoolCreate(uint32_t cMaxThreads, RTMSINTERVAL cMsMinIdle,
306	uint32_t cThreadsPushBackThreshold, uint32_t cMsMaxPushBack,
307	const char *pszName, PRTREQPOOL phPool);
308
309	/**
310	* Retains a reference to a request thread pool.
311	*
312	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
313	* @param hPool The request thread pool handle.
314	*/
315	RTDECL(uint32_t) RTReqPoolRetain(RTREQPOOL hPool);
316
317	/**
318	* Releases a reference to the request thread pool.
319	*
320	* When the reference count reaches zero, the request will be pooled for reuse.
321	*
322	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
323	* @param hPool The request thread pool handle.
324	*/
325	RTDECL(uint32_t) RTReqPoolRelease(RTREQPOOL hPool);
326
327	/**
328	* Request thread pool configuration variable.
329	*/
330	typedef enum RTREQPOOLCFGVAR
331	{
332	/** Invalid zero value. */
333	RTREQPOOLCFGVAR_INVALID = 0,
334	/** The desired RTTHREADTYPE of the worker threads. */
335	RTREQPOOLCFGVAR_THREAD_TYPE,
336	/** The RTTHREADFLAGS mask for the worker threads (not waitable). */
337	RTREQPOOLCFGVAR_THREAD_FLAGS,
338	/** The minimum number of threads to keep handy once spawned. */
339	RTREQPOOLCFGVAR_MIN_THREADS,
340	/** The maximum number of thread to start. */
341	RTREQPOOLCFGVAR_MAX_THREADS,
342	/** The minimum number of milliseconds a worker thread needs to be idle
343	* before we consider shutting it down. The other shutdown criteria
344	* being set by RTREQPOOLCFGVAR_MIN_THREADS. The value
345	* RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
346	RTREQPOOLCFGVAR_MS_MIN_IDLE,
347	/** The sleep period, in milliseoncds, to employ when idling. The value
348	* RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
349	RTREQPOOLCFGVAR_MS_IDLE_SLEEP,
350	/** The number of threads at which to start pushing back. The value
351	* UINT64_MAX is an alias for the current upper thread count limit, i.e.
352	* disabling push back. The value 0 (zero) is an alias for the current
353	* lower thread count, a good value to start pushing back at. The value
354	* must otherwise be within */
355	RTREQPOOLCFGVAR_PUSH_BACK_THRESHOLD,
356	/** The minimum push back time in milliseconds. */
357	RTREQPOOLCFGVAR_PUSH_BACK_MIN_MS,
358	/** The maximum push back time in milliseconds. */
359	RTREQPOOLCFGVAR_PUSH_BACK_MAX_MS,
360	/** The maximum number of free requests to keep handy for recycling. */
361	RTREQPOOLCFGVAR_MAX_FREE_REQUESTS,
362	/** The end of the range of valid config variables. */
363	RTREQPOOLCFGVAR_END,
364	/** Blow the type up to 32-bits. */
365	RTREQPOOLCFGVAR_32BIT_HACK = 0x7fffffff
366	} RTREQPOOLCFGVAR;
367
368
369	/**
370	* Sets a config variable for a request thread pool.
371	*
372	* @returns IPRT status code.
373	* @param hPool The pool handle.
374	* @param enmVar The variable to set.
375	* @param uValue The new value.
376	*/
377	RTDECL(int) RTReqPoolSetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar, uint64_t uValue);
378
379	/**
380	* Gets a config variable for a request thread pool.
381	*
382	* @returns The value, UINT64_MAX on invalid parameters.
383	* @param hPool The pool handle.
384	* @param enmVar The variable to query.
385	*/
386	RTDECL(uint64_t) RTReqPoolGetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar);
387
388	/**
389	* Request thread pool statistics value names.
390	*/
391	typedef enum RTREQPOOLSTAT
392	{
393	/** The invalid zero value, as per tradition. */
394	RTREQPOOLSTAT_INVALID = 0,
395	/** The current number of worker threads. */
396	RTREQPOOLSTAT_THREADS,
397	/** The number of threads that have been created. */
398	RTREQPOOLSTAT_THREADS_CREATED,
399	/** The total number of requests that have been processed. */
400	RTREQPOOLSTAT_REQUESTS_PROCESSED,
401	/** The total number of requests that have been submitted. */
402	RTREQPOOLSTAT_REQUESTS_SUBMITTED,
403	/** The total number of requests that have been cancelled. */
404	RTREQPOOLSTAT_REQUESTS_CANCELLED,
405	/** the current number of pending (waiting) requests. */
406	RTREQPOOLSTAT_REQUESTS_PENDING,
407	/** The current number of active (executing) requests. */
408	RTREQPOOLSTAT_REQUESTS_ACTIVE,
409	/** The current number of free (recycled) requests. */
410	RTREQPOOLSTAT_REQUESTS_FREE,
411	/** Total time the requests took to process. */
412	RTREQPOOLSTAT_NS_TOTAL_REQ_PROCESSING,
413	/** Total time the requests had to wait in the queue before being
414	* scheduled. */
415	RTREQPOOLSTAT_NS_TOTAL_REQ_QUEUED,
416	/** Average time the requests took to process. */
417	RTREQPOOLSTAT_NS_AVERAGE_REQ_PROCESSING,
418	/** Average time the requests had to wait in the queue before being
419	* scheduled. */
420	RTREQPOOLSTAT_NS_AVERAGE_REQ_QUEUED,
421	/** The end of the valid statistics value names. */
422	RTREQPOOLSTAT_END,
423	/** Blow the type up to 32-bit. */
424	RTREQPOOLSTAT_32BIT_HACK = 0x7fffffff
425	} RTREQPOOLSTAT;
426
427	/**
428	* Reads a statistics value from the request thread pool.
429	*
430	* @returns The value, UINT64_MAX if an invalid parameter was given.
431	* @param hPool The request thread pool handle.
432	* @param enmStat The statistics value to get.
433	*/
434	RTDECL(uint64_t) RTReqPoolGetStat(RTREQPOOL hPool, RTREQPOOLSTAT enmStat);
435
436	/**
437	* Allocates a request packet.
438	*
439	* This is mostly for internal use, please use the convenience methods.
440	*
441	* @returns IPRT status code.
442	*
443	* @param hPool The request thread pool handle.
444	* @param enmType Package type.
445	* @param phReq Where to store the handle to the new request.
446	*/
447	RTDECL(int) RTReqPoolAlloc(RTREQPOOL hPool, RTREQTYPE enmType, PRTREQ *phReq);
448
449	/**
450	* Calls a function on a worker thread.
451	*
452	* @returns IPRT status code.
453	* @param hPool The request thread pool handle.
454	* @param cMillies The number of milliseconds to wait for the request
455	* to be processed.
456	* @param phReq Where to store the pointer to the request. Optional
457	* when RTREQFLAGS_NO_WAIT is used.
458	* This variable will be set to NIL or a valid request
459	* handle not matter what happens.
460	* @param fFlags A combination of RTREQFLAGS values.
461	* @param pfnFunction The function to be called. Must be declared by a
462	* DECL macro because of calling conventions.
463	* @param cArgs The number of arguments in the ellipsis.
464	* @param ... Arguments.
465	*
466	* @remarks The function better avoid taking uint64_t and structs as part of the
467	* arguments (use pointers to these instead). In general anything
468	* that's larger than an uintptr_t is problematic.
469	*/
470	RTDECL(int) RTReqPoolCallEx(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
471
472
473	/**
474	* Calls a function on a worker thread.
475	*
476	* @returns IPRT status code.
477	* @param hPool The request thread pool handle.
478	* @param cMillies The number of milliseconds to wait for the request
479	* to be processed.
480	* @param phReq Where to store the pointer to the request. Optional
481	* when RTREQFLAGS_NO_WAIT is used.
482	* This variable will be set to NIL or a valid request
483	* handle not matter what happens.
484	* @param fFlags A combination of RTREQFLAGS values.
485	* @param pfnFunction The function to be called. Must be declared by a
486	* DECL macro because of calling conventions.
487	* @param cArgs The number of arguments in the variable argument
488	* list.
489	* @param va Arguments.
490	* @remarks See remarks on RTReqPoolCallEx.
491	*/
492	RTDECL(int) RTReqPoolCallExV(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list va);
493
494	/**
495	* Calls a function on a worker thread, wait for it to return.
496	*
497	* @returns IPRT status code returned by @a pfnFunction or request pool error.
498	* @param hPool The request thread pool handle.
499	* @param pfnFunction The function to be called. Must be declared by a
500	* DECL macro because of calling conventions. The
501	* function must return an int value compatible with
502	* the IPRT status code convention.
503	* @param cArgs The number of arguments in the elipsis.
504	* @param ... Arguments.
505	* @remarks See remarks on RTReqPoolCallEx.
506	*/
507	RTDECL(int) RTReqPoolCallWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
508
509	/**
510	* Calls a function on a worker thread, don't wait for it to return.
511	*
512	* @returns IPRT status code.
513	* @param hPool The request thread pool handle.
514	* @param pfnFunction The function to be called. Must be declared by a
515	* DECL macro because of calling conventions. The
516	* function should return an int value compatible with
517	* the IPRT status code convention, thought it's not
518	* all that important as it's thrown away.
519	* @param cArgs The number of arguments in the elipsis.
520	* @param ... Arguments.
521	* @remarks See remarks on RTReqPoolCallEx.
522	*/
523	RTDECL(int) RTReqPoolCallNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
524
525	/**
526	* Calls a void function on a worker thread.
527	*
528	* @returns IPRT status code.
529	* @param hPool The request thread pool handle.
530	* @param pfnFunction The function to be called. Must be declared by a
531	* DECL macro because of calling conventions. The
532	* function is taken to return void.
533	* @param cArgs The number of arguments in the elipsis.
534	* @param ... Arguments.
535	* @remarks See remarks on RTReqPoolCallEx.
536	*/
537	RTDECL(int) RTReqPoolCallVoidWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
538
539	/**
540	* Call a void function on a worker thread, don't wait for it to return.
541	*
542	* @returns IPRT status code.
543	* @param hPool The request thread pool handle.
544	* @param pfnFunction The function to be called. Must be declared by a
545	* DECL macro because of calling conventions. The
546	* function is taken to return void.
547	* @param cArgs The number of arguments in the elipsis.
548	* @param ... Arguments.
549	* @remarks See remarks on RTReqPoolCallEx.
550	*/
551	RTDECL(int) RTReqPoolCallVoidNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
552
553
554	/**
555	* Retains a reference to a request.
556	*
557	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
558	* @param hReq The request handle.
559	*/
560	RTDECL(uint32_t) RTReqRetain(PRTREQ hReq);
561
562	/**
563	* Releases a reference to the request.
564	*
565	* When the reference count reaches zero, the request will be pooled for reuse.
566	*
567	* @returns The new reference count, UINT32_MAX on invalid handle (asserted).
568	* @param hReq Package to release.
569	*/
570	RTDECL(uint32_t) RTReqRelease(PRTREQ hReq);
571
572	/**
573	* Queues a request.
574	*
575	* The request must be allocated using RTReqQueueAlloc() or RTReqPoolAlloc() and
576	* contain all the required data.
577	*
578	* If it's desired to poll on the completion of the request set cMillies
579	* to 0 and use RTReqWait() to check for completion. In the other case
580	* use RT_INDEFINITE_WAIT.
581	*
582	* @returns IPRT status code.
583	* Will not return VERR_INTERRUPTED.
584	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
585	*
586	* @param pReq The request to queue.
587	* @param cMillies Number of milliseconds to wait for the request to
588	* be completed. Use RT_INDEFINITE_WAIT to only
589	* wait till it's completed.
590	*/
591	RTDECL(int) RTReqSubmit(PRTREQ pReq, RTMSINTERVAL cMillies);
592
593	/**
594	* Cancels a pending request.
595	*
596	* @returns IPRT status code.
597	* @retval VERR_RT_REQUEST_STATE if the request is not cancellable.
598	*
599	* @param hReq The request to cancel.
600	*/
601	RTDECL(int) RTReqCancel(PRTREQ hReq);
602
603	/**
604	* Waits for a request to be completed.
605	*
606	* @returns IPRT status code.
607	* Will not return VERR_INTERRUPTED.
608	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
609	*
610	* @param pReq The request to wait for.
611	* @param cMillies Number of milliseconds to wait.
612	* Use RT_INDEFINITE_WAIT to only wait till it's completed.
613	*/
614	RTDECL(int) RTReqWait(PRTREQ pReq, RTMSINTERVAL cMillies);
615
616	/**
617	* Gets the status of the request.
618	*
619	* @returns IPRT status code.
620	*
621	* @param pReq The request to get the status for.
622	*/
623	RTDECL(int) RTReqGetStatus(PRTREQ pReq);
624
625	#endif /* IN_RING3 */
626
627
628	/** @} */
629
630	RT_C_DECLS_END
631
632	#endif /* !IPRT_INCLUDED_req_h */
633

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

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

Download in other formats: