VirtualBox

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

Last change on this file was 98103, checked in by vboxsync, 16 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
47RT_C_DECLS_BEGIN
48
49/** @defgroup grp_rt_req RTReq - Request Queue & Pool.
50 * @ingroup grp_rt
51 * @{
52 */
53
54/** Request queue handle. */
55typedef struct RTREQQUEUEINT *RTREQQUEUE;
56/** Pointer to a request queue handle. */
57typedef RTREQQUEUE *PRTREQQUEUE;
58/** NIL request queue handle. */
59#define NIL_RTREQQUEUE ((RTREQQUEUE)0)
60
61/** Request thread pool handle. */
62typedef struct RTREQPOOLINT *RTREQPOOL;
63/** Poiner to a request thread pool handle. */
64typedef RTREQPOOL *PRTREQPOOL;
65/** NIL request pool handle. */
66#define NIL_RTREQPOOL ((RTREQPOOL)0)
67
68
69/**
70 * Request type.
71 */
72typedef 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 */
85typedef 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. */
99typedef struct RTREQ RTREQ;
100/** Pointer to an RT request packet. */
101typedef 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 */
114RTDECL(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 */
122RTDECL(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 */
147RTDECL(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 */
173RTDECL(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 */
199RTDECL(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 */
228RTDECL(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 */
264RTDECL(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 */
274RTDECL(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 */
288RTDECL(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 */
315RTDECL(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 */
325RTDECL(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 */
335RTDECL(uint32_t) RTReqPoolRelease(RTREQPOOL hPool);
336
337/**
338 * Request thread pool configuration variable.
339 */
340typedef 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 */
387RTDECL(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 */
396RTDECL(uint64_t) RTReqPoolGetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar);
397
398/**
399 * Request thread pool statistics value names.
400 */
401typedef 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 */
444RTDECL(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 */
457RTDECL(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 */
480RTDECL(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 */
502RTDECL(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 */
517RTDECL(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 */
533RTDECL(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 */
547RTDECL(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 */
561RTDECL(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 */
570RTDECL(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 */
580RTDECL(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 */
601RTDECL(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 */
611RTDECL(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 */
624RTDECL(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 */
633RTDECL(int) RTReqGetStatus(PRTREQ pReq);
634
635#endif /* IN_RING3 */
636
637
638/** @} */
639
640RT_C_DECLS_END
641
642#endif /* !IPRT_INCLUDED_req_h */
643
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use