Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 643 insertions, 0 deletions

diff --git a/include/iprt/req.h b/include/iprt/req.h
new file mode 100644
index 00000000..a017e9e1
--- /dev/null
+++ b/include/iprt/req.h
@@ -0,0 +1,643 @@
+/** @file
+ * IPRT - Request Queue & Pool.
+ */
+
+/*
+ * Copyright (C) 2006-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef IPRT_INCLUDED_req_h
+#define IPRT_INCLUDED_req_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <iprt/cdefs.h>
+#include <iprt/types.h>
+
+#include <iprt/stdarg.h>
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_rt_req    RTReq - Request Queue & Pool.
+ * @ingroup grp_rt
+ * @{
+ */
+
+/** Request queue handle. */
+typedef struct RTREQQUEUEINT *RTREQQUEUE;
+/** Pointer to a request queue handle. */
+typedef RTREQQUEUE *PRTREQQUEUE;
+/** NIL request queue handle. */
+#define NIL_RTREQQUEUE      ((RTREQQUEUE)0)
+
+/** Request thread pool handle. */
+typedef struct RTREQPOOLINT *RTREQPOOL;
+/** Poiner to a request thread pool handle. */
+typedef RTREQPOOL *PRTREQPOOL;
+/** NIL request pool handle. */
+#define NIL_RTREQPOOL       ((RTREQPOOL)0)
+
+
+/**
+ * Request type.
+ */
+typedef enum RTREQTYPE
+{
+    /** Invalid request. */
+    RTREQTYPE_INVALID = 0,
+    /** RT: Internal. */
+    RTREQTYPE_INTERNAL,
+    /** Maximum request type (exclusive). Used for validation. */
+    RTREQTYPE_MAX
+} RTREQTYPE;
+
+/**
+ * Request flags.
+ */
+typedef enum RTREQFLAGS
+{
+    /** The request returns a IPRT status code. */
+    RTREQFLAGS_IPRT_STATUS  = 0,
+    /** The request is a void request and have no status code. */
+    RTREQFLAGS_VOID         = 1,
+    /** Return type mask. */
+    RTREQFLAGS_RETURN_MASK  = 1,
+    /** Caller does not wait on the packet. */
+    RTREQFLAGS_NO_WAIT      = 2
+} RTREQFLAGS;
+
+
+/** A request packet. */
+typedef struct RTREQ RTREQ;
+/** Pointer to an RT request packet. */
+typedef RTREQ *PRTREQ;
+/** Nil request handle. */
+#define NIL_RTREQ           ((PRTREQ)0)
+
+
+#ifdef IN_RING3
+
+/**
+ * Create a request packet queue
+ *
+ * @returns IPRT status code.
+ * @param   phQueue         Where to store the request queue handle.
+ */
+RTDECL(int) RTReqQueueCreate(PRTREQQUEUE phQueue);
+
+/**
+ * Destroy a request packet queue
+ *
+ * @returns IPRT status code.
+ * @param   hQueue          The request queue.
+ */
+RTDECL(int) RTReqQueueDestroy(RTREQQUEUE hQueue);
+
+/**
+ * Process one or more request packets
+ *
+ * @returns IPRT status code.  Any non-VINF_SUCCESS returns from request
+ *          processing is immediately propagated to the caller.
+ * @retval  VERR_TIMEOUT if @a cMillies was reached without the packet being
+ *          added.
+ * @retval  VERR_INVALID_HANDLE if @a hQueue not a valid queue handle.
+ *
+ * @param   hQueue          The request queue.
+ * @param   cMillies        Max number of milliseconds to wait for a pending
+ *                          request.  This is not adjusted down before another
+ *                          wait, so the function may end up waiting for much
+ *                          longer than the given amount if there are requests
+ *                          trickling in at a rate slightly higher than the
+ *                          timeout.
+ *
+ *                          Use RT_INDEFINITE_WAIT to process requests until a
+ *                          non-VINF_SUCCESS return code is encountered.
+ *
+ * @remarks The function may repeatedly try wait for @a cMillies on new
+ *          requests if requests arrive before it times out.
+ */
+RTDECL(int) RTReqQueueProcess(RTREQQUEUE hQueue, RTMSINTERVAL cMillies);
+
+/**
+ * Allocate and queue a call request.
+ *
+ * If it's desired to poll on the completion of the request set cMillies
+ * to 0 and use RTReqWait() to check for completion. In the other case
+ * use RT_INDEFINITE_WAIT.
+ * The returned request packet must be freed using RTReqRelease().
+ *
+ * @returns iprt statuscode.
+ *          Will not return VERR_INTERRUPTED.
+ * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
+ *
+ * @param   hQueue          The request queue.
+ * @param   ppReq           Where to store the pointer to the request.
+ *                          This will be NULL or a valid request pointer no matter what happens.
+ * @param   cMillies        Number of milliseconds to wait for the request to
+ *                          be completed. Use RT_INDEFINITE_WAIT to only
+ *                          wait till it's completed.
+ * @param   pfnFunction     Pointer to the function to call.
+ * @param   cArgs           Number of arguments following in the ellipsis.
+ * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqQueueCallV.
+ */
+RTDECL(int) RTReqQueueCall(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
+
+/**
+ * Allocate and queue a call request to a void function.
+ *
+ * If it's desired to poll on the completion of the request set cMillies
+ * to 0 and use RTReqWait() to check for completion. In the other case
+ * use RT_INDEFINITE_WAIT.
+ * The returned request packet must be freed using RTReqRelease().
+ *
+ * @returns IPRT status code.
+ *          Will not return VERR_INTERRUPTED.
+ * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
+ *
+ * @param   hQueue          The request queue.
+ * @param   ppReq           Where to store the pointer to the request.
+ *                          This will be NULL or a valid request pointer no matter what happens.
+ * @param   cMillies        Number of milliseconds to wait for the request to
+ *                          be completed. Use RT_INDEFINITE_WAIT to only
+ *                          wait till it's completed.
+ * @param   pfnFunction     Pointer to the function to call.
+ * @param   cArgs           Number of arguments following in the ellipsis.
+ * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqQueueCallV.
+ */
+RTDECL(int) RTReqQueueCallVoid(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
+
+/**
+ * Allocate and queue a call request to a void function.
+ *
+ * If it's desired to poll on the completion of the request set cMillies
+ * to 0 and use RTReqWait() to check for completion. In the other case
+ * use RT_INDEFINITE_WAIT.
+ * The returned request packet must be freed using RTReqRelease().
+ *
+ * @returns IPRT status code.
+ *          Will not return VERR_INTERRUPTED.
+ * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
+ *
+ * @param   hQueue          The request queue.
+ * @param   ppReq           Where to store the pointer to the request.  Optional
+ *                          when RTREQFLAGS_NO_WAIT is used.
+ *                          This variable will be set to NIL or a valid request
+ *                          handle no matter what happens.
+ * @param   cMillies        Number of milliseconds to wait for the request to
+ *                          be completed. Use RT_INDEFINITE_WAIT to only
+ *                          wait till it's completed.
+ * @param   fFlags          A combination of the RTREQFLAGS values.
+ * @param   pfnFunction     Pointer to the function to call.
+ * @param   cArgs           Number of arguments following in the ellipsis.
+ * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqQueueCallV.
+ */
+RTDECL(int) RTReqQueueCallEx(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
+
+/**
+ * Allocate and queue a call request.
+ *
+ * If it's desired to poll on the completion of the request set cMillies
+ * to 0 and use RTReqWait() to check for completion. In the other case
+ * use RT_INDEFINITE_WAIT.
+ * The returned request packet must be freed using RTReqRelease().
+ *
+ * @returns IPRT status code.
+ *          Will not return VERR_INTERRUPTED.
+ * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
+ *
+ * @param   hQueue          The request queue.
+ * @param   ppReq           Where to store the pointer to the request.  Optional
+ *                          when RTREQFLAGS_NO_WAIT is used.
+ *                          This variable will be set to NIL or a valid request
+ *                          handle no matter what happens.
+ * @param   cMillies        Number of milliseconds to wait for the request to
+ *                          be completed. Use RT_INDEFINITE_WAIT to only
+ *                          wait till it's completed.
+ * @param   fFlags          A combination of the RTREQFLAGS values.
+ * @param   pfnFunction     Pointer to the function to call.
+ * @param   cArgs           Number of arguments following in the ellipsis.
+ * @param   Args            Variable argument vector.
+ *
+ * @remarks Caveats:
+ *              - Do not pass anything which is larger than an uintptr_t.
+ *              - 64-bit integers are larger than uintptr_t on 32-bit hosts.
+ *                Pass integers > 32-bit by reference (pointers).
+ *              - Don't use NULL since it should be the integer 0 in C++ and may
+ *                therefore end up with garbage in the bits 63:32 on 64-bit
+ *                hosts because 'int' is 32-bit.
+ *                Use (void *)NULL or (uintptr_t)0 instead of NULL.
+ */
+RTDECL(int) RTReqQueueCallV(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
+
+/**
+ * Checks if the queue is busy or not.
+ *
+ * The caller is responsible for dealing with any concurrent submitts.
+ *
+ * @returns true if busy, false if idle.
+ * @param   hQueue              The queue.
+ */
+RTDECL(bool) RTReqQueueIsBusy(RTREQQUEUE hQueue);
+
+/**
+ * Allocates a request packet.
+ *
+ * The caller allocates a request packet, fills in the request data
+ * union and queues the request.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   hQueue          The request queue.
+ * @param   enmType         Package type.
+ * @param   phReq           Where to store the handle to the new request.
+ */
+RTDECL(int) RTReqQueueAlloc(RTREQQUEUE hQueue, RTREQTYPE enmType, PRTREQ *phReq);
+
+
+/**
+ * Creates a request thread pool.
+ *
+ * The core configuration is given as parameters, finer pool tuning can be
+ * achieved via RTReqPoolSetCfgVar.
+ *
+ * @returns IPRT status code.
+ * @param   cMaxThreads                 The maximum number of worker threads.
+ *                                      UINT32_MAX is an alias for the highest
+ *                                      allowed thread count.
+ * @param   cMsMinIdle                  The number of milliseconds a worker
+ *                                      thread needs to be idle before it is
+ *                                      considered for shutdown. The value
+ *                                      RT_INDEFINITE_WAIT disables automatic
+ *                                      idle thread shutdown.
+ * @param   cThreadsPushBackThreshold   At which worker thread count the push
+ *                                      back should kick in.
+ * @param   cMsMaxPushBack              The max number of milliseconds to push
+ *                                      back a submitter.  UINT32_MAX is an
+ *                                      alias for the highest allowed push back.
+ * @param   pszName                     The pool name. Keep it short as it is
+ *                                      used for naming worker threads.
+ * @param   phPool                      Where to return the pool handle.
+ */
+RTDECL(int) RTReqPoolCreate(uint32_t cMaxThreads, RTMSINTERVAL cMsMinIdle,
+                            uint32_t cThreadsPushBackThreshold, uint32_t cMsMaxPushBack,
+                            const char *pszName, PRTREQPOOL phPool);
+
+/**
+ * Retains a reference to a request thread pool.
+ *
+ * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
+ * @param   hPool           The request thread pool handle.
+ */
+RTDECL(uint32_t) RTReqPoolRetain(RTREQPOOL hPool);
+
+/**
+ * Releases a reference to the request thread pool.
+ *
+ * When the reference count reaches zero, the request will be pooled for reuse.
+ *
+ * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
+ * @param   hPool           The request thread pool handle.
+ */
+RTDECL(uint32_t) RTReqPoolRelease(RTREQPOOL hPool);
+
+/**
+ * Request thread pool configuration variable.
+ */
+typedef enum RTREQPOOLCFGVAR
+{
+    /** Invalid zero value. */
+    RTREQPOOLCFGVAR_INVALID = 0,
+    /** The desired RTTHREADTYPE of the worker threads. */
+    RTREQPOOLCFGVAR_THREAD_TYPE,
+    /** The RTTHREADFLAGS mask for the worker threads (not waitable). */
+    RTREQPOOLCFGVAR_THREAD_FLAGS,
+    /** The minimum number of threads to keep handy once spawned. */
+    RTREQPOOLCFGVAR_MIN_THREADS,
+    /** The maximum number of thread to start. */
+    RTREQPOOLCFGVAR_MAX_THREADS,
+    /** The minimum number of milliseconds a worker thread needs to be idle
+     * before we consider shutting it down.  The other shutdown criteria
+     * being set by RTREQPOOLCFGVAR_MIN_THREADS.  The value
+     * RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
+    RTREQPOOLCFGVAR_MS_MIN_IDLE,
+    /** The sleep period, in milliseoncds, to employ when idling. The value
+     * RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
+    RTREQPOOLCFGVAR_MS_IDLE_SLEEP,
+    /** The number of threads at which to start pushing back. The value
+     *  UINT64_MAX is an alias for the current upper thread count limit, i.e.
+     *  disabling push back.  The value 0 (zero) is an alias for the current
+     *  lower thread count, a good value to start pushing back at.  The value
+     *  must otherwise be within  */
+    RTREQPOOLCFGVAR_PUSH_BACK_THRESHOLD,
+    /** The minimum push back time in milliseconds. */
+    RTREQPOOLCFGVAR_PUSH_BACK_MIN_MS,
+    /** The maximum push back time in milliseconds. */
+    RTREQPOOLCFGVAR_PUSH_BACK_MAX_MS,
+    /** The maximum number of free requests to keep handy for recycling. */
+    RTREQPOOLCFGVAR_MAX_FREE_REQUESTS,
+    /** The end of the range of valid config variables. */
+    RTREQPOOLCFGVAR_END,
+    /** Blow the type up to 32-bits. */
+    RTREQPOOLCFGVAR_32BIT_HACK = 0x7fffffff
+} RTREQPOOLCFGVAR;
+
+
+/**
+ * Sets a config variable for a request thread pool.
+ *
+ * @returns IPRT status code.
+ * @param   hPool           The pool handle.
+ * @param   enmVar          The variable to set.
+ * @param   uValue          The new value.
+ */
+RTDECL(int) RTReqPoolSetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar, uint64_t uValue);
+
+/**
+ * Gets a config variable for a request thread pool.
+ *
+ * @returns The value, UINT64_MAX on invalid parameters.
+ * @param   hPool           The pool handle.
+ * @param   enmVar          The variable to query.
+ */
+RTDECL(uint64_t) RTReqPoolGetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar);
+
+/**
+ * Request thread pool statistics value names.
+ */
+typedef enum RTREQPOOLSTAT
+{
+    /** The invalid zero value, as per tradition. */
+    RTREQPOOLSTAT_INVALID = 0,
+    /** The current number of worker threads. */
+    RTREQPOOLSTAT_THREADS,
+    /** The number of threads that have been created. */
+    RTREQPOOLSTAT_THREADS_CREATED,
+    /** The total number of requests that have been processed. */
+    RTREQPOOLSTAT_REQUESTS_PROCESSED,
+    /** The total number of requests that have been submitted. */
+    RTREQPOOLSTAT_REQUESTS_SUBMITTED,
+    /** The total number of requests that have been cancelled. */
+    RTREQPOOLSTAT_REQUESTS_CANCELLED,
+    /** the current number of pending (waiting) requests. */
+    RTREQPOOLSTAT_REQUESTS_PENDING,
+    /** The current number of active (executing) requests. */
+    RTREQPOOLSTAT_REQUESTS_ACTIVE,
+    /** The current number of free (recycled) requests. */
+    RTREQPOOLSTAT_REQUESTS_FREE,
+    /** Total time the requests took to process. */
+    RTREQPOOLSTAT_NS_TOTAL_REQ_PROCESSING,
+    /** Total time the requests had to wait in the queue before being
+     * scheduled. */
+    RTREQPOOLSTAT_NS_TOTAL_REQ_QUEUED,
+    /** Average time the requests took to process. */
+    RTREQPOOLSTAT_NS_AVERAGE_REQ_PROCESSING,
+    /** Average time the requests had to wait in the queue before being
+     * scheduled. */
+    RTREQPOOLSTAT_NS_AVERAGE_REQ_QUEUED,
+    /** The end of the valid statistics value names. */
+    RTREQPOOLSTAT_END,
+    /** Blow the type up to 32-bit. */
+    RTREQPOOLSTAT_32BIT_HACK = 0x7fffffff
+} RTREQPOOLSTAT;
+
+/**
+ * Reads a statistics value from the request thread pool.
+ *
+ * @returns The value, UINT64_MAX if an invalid parameter was given.
+ * @param   hPool           The request thread pool handle.
+ * @param   enmStat         The statistics value to get.
+ */
+RTDECL(uint64_t) RTReqPoolGetStat(RTREQPOOL hPool, RTREQPOOLSTAT enmStat);
+
+/**
+ * Allocates a request packet.
+ *
+ * This is mostly for internal use, please use the convenience methods.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   hPool           The request thread pool handle.
+ * @param   enmType         Package type.
+ * @param   phReq           Where to store the handle to the new request.
+ */
+RTDECL(int) RTReqPoolAlloc(RTREQPOOL hPool, RTREQTYPE enmType, PRTREQ *phReq);
+
+/**
+ * Calls a function on a worker thread.
+ *
+ * @returns IPRT status code.
+ * @param   hPool           The request thread pool handle.
+ * @param   cMillies        The number of milliseconds to wait for the request
+ *                          to be processed.
+ * @param   phReq           Where to store the pointer to the request.  Optional
+ *                          when RTREQFLAGS_NO_WAIT is used.
+ *                          This variable will be set to NIL or a valid request
+ *                          handle no matter what happens.
+ * @param   fFlags          A combination of RTREQFLAGS values.
+ * @param   pfnFunction     The function to be called.  Must be declared by a
+ *                          DECL macro because of calling conventions.
+ * @param   cArgs           The number of arguments in the ellipsis.
+ * @param   ...             Arguments.
+ *
+ * @remarks The function better avoid taking uint64_t and structs as part of the
+ *          arguments (use pointers to these instead).  In general anything
+ *          that's larger than an uintptr_t is problematic.
+ */
+RTDECL(int) RTReqPoolCallEx(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
+
+
+/**
+ * Calls a function on a worker thread.
+ *
+ * @returns IPRT status code.
+ * @param   hPool           The request thread pool handle.
+ * @param   cMillies        The number of milliseconds to wait for the request
+ *                          to be processed.
+ * @param   phReq           Where to store the pointer to the request.  Optional
+ *                          when RTREQFLAGS_NO_WAIT is used.
+ *                          This variable will be set to NIL or a valid request
+ *                          handle no matter what happens.
+ * @param   fFlags          A combination of RTREQFLAGS values.
+ * @param   pfnFunction     The function to be called.  Must be declared by a
+ *                          DECL macro because of calling conventions.
+ * @param   cArgs           The number of arguments in the variable argument
+ *                          list.
+ * @param   va              Arguments.
+ * @remarks See remarks on RTReqPoolCallEx.
+ */
+RTDECL(int) RTReqPoolCallExV(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list va);
+
+/**
+ * Calls a function on a worker thread, wait for it to return.
+ *
+ * @returns IPRT status code returned by @a pfnFunction or request pool error.
+ * @param   hPool           The request thread pool handle.
+ * @param   pfnFunction     The function to be called.  Must be declared by a
+ *                          DECL macro because of calling conventions.  The
+ *                          function must return an int value compatible with
+ *                          the IPRT status code convention.
+ * @param   cArgs           The number of arguments in the elipsis.
+ * @param   ...             Arguments.
+ * @remarks See remarks on RTReqPoolCallEx.
+ */
+RTDECL(int) RTReqPoolCallWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
+
+/**
+ * Calls a function on a worker thread, don't wait for it to return.
+ *
+ * @returns IPRT status code.
+ * @param   hPool           The request thread pool handle.
+ * @param   pfnFunction     The function to be called.  Must be declared by a
+ *                          DECL macro because of calling conventions.  The
+ *                          function should return an int value compatible with
+ *                          the IPRT status code convention, thought it's not
+ *                          all that important as it's thrown away.
+ * @param   cArgs           The number of arguments in the elipsis.
+ * @param   ...             Arguments.
+ * @remarks See remarks on RTReqPoolCallEx.
+ */
+RTDECL(int) RTReqPoolCallNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
+
+/**
+ * Calls a void function on a worker thread.
+ *
+ * @returns IPRT status code.
+ * @param   hPool           The request thread pool handle.
+ * @param   pfnFunction     The function to be called.  Must be declared by a
+ *                          DECL macro because of calling conventions.  The
+ *                          function is taken to return void.
+ * @param   cArgs           The number of arguments in the elipsis.
+ * @param   ...             Arguments.
+ * @remarks See remarks on RTReqPoolCallEx.
+ */
+RTDECL(int) RTReqPoolCallVoidWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
+
+/**
+ * Call a void function on a worker thread, don't wait for it to return.
+ *
+ * @returns IPRT status code.
+ * @param   hPool           The request thread pool handle.
+ * @param   pfnFunction     The function to be called.  Must be declared by a
+ *                          DECL macro because of calling conventions.  The
+ *                          function is taken to return void.
+ * @param   cArgs           The number of arguments in the elipsis.
+ * @param   ...             Arguments.
+ * @remarks See remarks on RTReqPoolCallEx.
+ */
+RTDECL(int) RTReqPoolCallVoidNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
+
+
+/**
+ * Retains a reference to a request.
+ *
+ * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
+ * @param   hReq            The request handle.
+ */
+RTDECL(uint32_t) RTReqRetain(PRTREQ hReq);
+
+/**
+ * Releases a reference to the request.
+ *
+ * When the reference count reaches zero, the request will be pooled for reuse.
+ *
+ * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
+ * @param   hReq            Package to release.
+ */
+RTDECL(uint32_t) RTReqRelease(PRTREQ hReq);
+
+/**
+ * Queues a request.
+ *
+ * The request must be allocated using RTReqQueueAlloc() or RTReqPoolAlloc() and
+ * contain all the required data.
+ *
+ * If it's desired to poll on the completion of the request set cMillies
+ * to 0 and use RTReqWait() to check for completion. In the other case
+ * use RT_INDEFINITE_WAIT.
+ *
+ * @returns IPRT status code.
+ *          Will not return VERR_INTERRUPTED.
+ * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
+ *
+ * @param   pReq            The request to queue.
+ * @param   cMillies        Number of milliseconds to wait for the request to
+ *                          be completed. Use RT_INDEFINITE_WAIT to only
+ *                          wait till it's completed.
+ */
+RTDECL(int) RTReqSubmit(PRTREQ pReq, RTMSINTERVAL cMillies);
+
+/**
+ * Cancels a pending request.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_RT_REQUEST_STATE if the request is not cancellable.
+ *
+ * @param   hReq            The request to cancel.
+ */
+RTDECL(int) RTReqCancel(PRTREQ hReq);
+
+/**
+ * Waits for a request to be completed.
+ *
+ * @returns IPRT status code.
+ *          Will not return VERR_INTERRUPTED.
+ * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
+ *
+ * @param   pReq            The request to wait for.
+ * @param   cMillies        Number of milliseconds to wait.
+ *                          Use RT_INDEFINITE_WAIT to only wait till it's completed.
+ */
+RTDECL(int) RTReqWait(PRTREQ pReq, RTMSINTERVAL cMillies);
+
+/**
+ * Gets the status of the request.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pReq            The request to get the status for.
+ */
+RTDECL(int) RTReqGetStatus(PRTREQ pReq);
+
+#endif /* IN_RING3 */
+
+
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_req_h */
+