req.h

Last change on this file was 106061, checked in by vboxsync, 2 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: 25.9 KB

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

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

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

Download in other formats: