req.h@ 98341

Last change on this file since 98341 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property eol-style set to `native` Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 24.9 KB

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

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

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

Download in other formats: