36411046d85fccaa66061120a064225fd1b5ae01vboxsync * IPRT - Request Queue & Pool.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * Copyright (C) 2006-2011 Oracle Corporation
c98fb3e16fcd571a790eab772c0c66173d225205vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
c98fb3e16fcd571a790eab772c0c66173d225205vboxsync * available from http://www.virtualbox.org. This file is free software;
c98fb3e16fcd571a790eab772c0c66173d225205vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * The contents of this file may alternatively be used under the terms
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * of the Common Development and Distribution License Version 1.0
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution, in which case the provisions of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * CDDL are applicable instead of those of the GPL.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * You may elect to license modified versions of this file under the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * terms and conditions of either the GPL or the CDDL or both.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** @defgroup grp_rt_req RTReq - Request Queue & Pool.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @ingroup grp_rt
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** Request queue handle. */
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** Pointer to a request queue handle. */
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** NIL request queue handle. */
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** Request thread pool handle. */
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** Poiner to a request thread pool handle. */
36411046d85fccaa66061120a064225fd1b5ae01vboxsync/** NIL request pool handle. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Request type.
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Invalid request. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** RT: Internal. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Maximum request type (exclusive). Used for validation. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Request flags.
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request returns a iprt status code. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request is a void request and have no status code. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Return type mask. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Caller does not wait on the packet, Queue process thread will free it. */
4f3f6eb7aecf332523a1b44ff1e0cda506408273vboxsync/** A request packet. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync/** Pointer to an RT request packet. */
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync/** Nil request handle. */
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Create a request packet queue
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param phQueue Where to store the request queue handle.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Destroy a request packet queue
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Process one or more request packets
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being added.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for a pending request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Use RT_INDEFINITE_WAIT to only wait till one is added.
36411046d85fccaa66061120a064225fd1b5ae01vboxsyncRTDECL(int) RTReqQueueProcess(RTREQQUEUE hQueue, RTMSINTERVAL cMillies);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * to 0 and use RTReqWait() to check for completion. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * The returned request packet must be freed using RTReqRelease().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt statuscode.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * This will be NULL or a valid request pointer not matter what happens.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ... Function arguments.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @remarks See remarks on RTReqQueueCallV.
36411046d85fccaa66061120a064225fd1b5ae01vboxsyncRTDECL(int) RTReqQueueCall(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request to a void function.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * to 0 and use RTReqWait() to check for completion. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * The returned request packet must be freed using RTReqRelease().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * This will be NULL or a valid request pointer not matter what happens.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ... Function arguments.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @remarks See remarks on RTReqQueueCallV.
36411046d85fccaa66061120a064225fd1b5ae01vboxsyncRTDECL(int) RTReqQueueCallVoid(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request to a void function.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * to 0 and use RTReqWait() to check for completion. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * The returned request packet must be freed using RTReqRelease().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * This will be NULL or a valid request pointer not matter what happens, unless fFlags
00314ca59bb0358d05053ee753174724d82adff4vboxsync * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param fFlags A combination of the RTREQFLAGS values.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ... Function arguments.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @remarks See remarks on RTReqQueueCallV.
36411046d85fccaa66061120a064225fd1b5ae01vboxsyncRTDECL(int) RTReqQueueCallEx(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * to 0 and use RTReqWait() to check for completion. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * The returned request packet must be freed using RTReqRelease().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * This will be NULL or a valid request pointer not matter what happens, unless fFlags
00314ca59bb0358d05053ee753174724d82adff4vboxsync * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param fFlags A combination of the RTREQFLAGS values.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param Args Variable argument vector.
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * @remarks Caveats:
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * - Do not pass anything which is larger than an uintptr_t.
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * - 64-bit integers are larger than uintptr_t on 32-bit hosts.
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * Pass integers > 32-bit by reference (pointers).
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * - Don't use NULL since it should be the integer 0 in C++ and may
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * therefore end up with garbage in the bits 63:32 on 64-bit
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * hosts because 'int' is 32-bit.
89ed8fe4cc94bfa1639d2101d5e076f2cae971ddvboxsync * Use (void *)NULL or (uintptr_t)0 instead of NULL.
36411046d85fccaa66061120a064225fd1b5ae01vboxsyncRTDECL(int) RTReqQueueCallV(RTREQQUEUE hQueue, PRTREQ *ppReq, RTMSINTERVAL cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * Checks if the queue is busy or not.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * The caller is responsible for dealing with any concurrent submitts.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @returns true if busy, false if idle.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocates a request packet.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The caller allocates a request packet, fills in the request data
00314ca59bb0358d05053ee753174724d82adff4vboxsync * union and queues the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * @param hQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param enmType Package type.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param phReq Where to store the handle to the new request.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsyncRTDECL(int) RTReqQueueAlloc(RTREQQUEUE hQueue, RTREQTYPE enmType, PRTREQ *phReq);
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * Creates a request thread pool.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * The core configuration is given as parameters, finer pool tuning can be
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * achieved via RTReqPoolSetCfgVar.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @returns IPRT status code.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @param cMaxThreads The maximum number of worker threads.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * UINT32_MAX is an alias for the highest
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * allowed thread count.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @param cMsMinIdle The number of milliseconds a worker
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * thread needs to be idle before it is
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * considered for shutdown. The value
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * RT_INDEFINITE_WAIT disables automatic
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * idle thread shutdown.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @param cThreadsPushBackThreshold At which worker thread count the push
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * back should kick in.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @param cMsMaxPushBack The max number of milliseconds to push
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * back a submitter. UINT32_MAX is an
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * alias for the highest allowed push back.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @param pszName The pool name. Keep it short as it is
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * used for naming worker threads.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @param phPool Where to return the pool handle.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCreate(uint32_t cMaxThreads, RTMSINTERVAL cMsMinIdle,
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync uint32_t cThreadsPushBackThreshold, uint32_t cMsMaxPushBack,
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * Retainsa reference to a request thread pool.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param hPool The request thread pool handle.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * Releases a reference to the request thread pool.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * When the reference count reaches zero, the request will be pooled for reuse.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param hPool The request thread pool handle.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * Request thread pool configuration variable.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Invalid zero value. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The desired RTTHREADTYPE of the worker threads. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The minimum number of threads to keep handy once spawned. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The maximum number of thread to start. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The minimum number of milliseconds a worker thread needs to be idle
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * before we consider shutting it down. The other shutdown criteria
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * being set by RTREQPOOLCFGVAR_MIN_THREADS. The value
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The sleep period, in milliseoncds, to employ when idling. The value
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * RT_INDEFINITE_WAIT can be used to disable shutting down idle threads. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The number of threads at which to start pushing back. The value
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * UINT64_MAX is an alias for the current upper thread count limit, i.e.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * disabling push back. The value 0 (zero) is an alias for the current
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * lower thread count, a good value to start pushing back at. The value
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * must otherwise be within */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The minimum push back time in milliseconds. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The maximum push back time in milliseconds. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The maximum number of free requests to keep handy for recycling. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The end of the range of valid config variables. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Blow the type up to 32-bits. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * Sets a config variable for a request thread pool.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @returns IPRT status code.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param hPool The pool handle.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param enmVar The variable to set.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param uValue The new value.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsyncRTDECL(int) RTReqPoolSetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar, uint64_t uValue);
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * Gets a config variable for a request thread pool.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsync * @returns The value, UINT64_MAX on invalid parameters.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param hPool The pool handle.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param enmVar The variable to query.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(uint64_t) RTReqPoolGetCfgVar(RTREQPOOL hPool, RTREQPOOLCFGVAR enmVar);
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * Request thread pool statistics value names.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The invalid zero value, as per tradition. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The current number of worker threads. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The number of threads that have been created. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The total number of requests that have been processed. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The total number of requests that have been submitted. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** the current number of pending (waiting) requests. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The current number of active (executing) requests. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The current number of free (recycled) requests. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Total time the requests took to process. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Total time the requests had to wait in the queue before being
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * scheduled. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Average time the requests took to process. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Average time the requests had to wait in the queue before being
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * scheduled. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** The end of the valid statistics value names. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync /** Blow the type up to 32-bit. */
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * Read a statistics value from the request thread pool.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @returns The value, UINT64_MAX if an invalid parameter was given.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param hPool The request thread pool handle.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsync * @param enmStat The statistics value to get.
c1b4529a269091edd0274bd98d35b75663fd66c0vboxsyncRTDECL(uint64_t) RTReqPoolGetStat(RTREQPOOL hPool, RTREQPOOLSTAT enmStat);
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * Allocates a request packet.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * This is mostly for internal use, please use the convenience methods.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param hPool The request thread pool handle.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param enmType Package type.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param phReq Where to store the handle to the new request.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsyncRTDECL(int) RTReqPoolAlloc(RTREQPOOL hPool, RTREQTYPE enmType, PRTREQ *phReq);
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * Call a function on a worker thread.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @returns IPRT status code.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param hPool The request thread pool handle.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cMillies The number of milliseconds to wait for the request
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * to be processed.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param phReq Where to return the request. Can be NULL if the
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * RTREQFLAGS_NO_WAIT flag is used.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param fFlags A combination of RTREQFLAGS values.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param pfnFunction The function to be called. Must be declared by a
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * DECL macro because of calling conventions.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cArgs The number of arguments in the ellipsis.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param ... Arguments.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @remarks The function better avoid taking uint64_t and structs as part of the
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * arguments (use pointers to these instead). In general anything
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * that's larger than an uintptr_t is problematic.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCallEx( RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * Call a function on a worker thread.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @returns IPRT status code.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param hPool The request thread pool handle.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cMillies The number of milliseconds to wait for the request
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * to be processed.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param phReq Where to return the request. Can be NULL if the
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * RTREQFLAGS_NO_WAIT flag is used.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param fFlags A combination of RTREQFLAGS values.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param pfnFunction The function to be called. Must be declared by a
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * DECL macro because of calling conventions.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cArgs The number of arguments in the variable argument
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param va Arguments.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @remarks See remarks on RTReqPoolCallEx.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCallExV(RTREQPOOL hPool, RTMSINTERVAL cMillies, PRTREQ *phReq, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list va);
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * Call a function on a worker thread, wait for it to return.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @returns IPRT status code returned by @a pfnFunction or request pool error.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param hPool The request thread pool handle.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param pfnFunction The function to be called. Must be declared by a
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * DECL macro because of calling conventions. The
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * function must return an int value compatible with
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * the IPRT status code convention.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cArgs The number of arguments in the elipsis.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param ... Arguments.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @remarks See remarks on RTReqPoolCallEx.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCallWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * Call a function on a worker thread, don't wait for it to return.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @returns IPRT status code.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param hPool The request thread pool handle.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param pfnFunction The function to be called. Must be declared by a
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * DECL macro because of calling conventions. The
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * function should return an int value compatible with
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * the IPRT status code convention, thought it's not
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * all that important as it's thrown away.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cArgs The number of arguments in the elipsis.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param ... Arguments.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @remarks See remarks on RTReqPoolCallEx.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCallNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * Call a void function on a worker thread.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @returns IPRT status code.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param hPool The request thread pool handle.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param pfnFunction The function to be called. Must be declared by a
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * DECL macro because of calling conventions. The
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * function is taken to return void.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cArgs The number of arguments in the elipsis.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param ... Arguments.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @remarks See remarks on RTReqPoolCallEx.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCallVoidWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * Call a void function on a worker thread, don't wait for it to return.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @returns IPRT status code.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param hPool The request thread pool handle.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param pfnFunction The function to be called. Must be declared by a
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * DECL macro because of calling conventions. The
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * function is taken to return void.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param cArgs The number of arguments in the elipsis.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @param ... Arguments.
549538c4871154e06dfcecd387a0e10f83e02a31vboxsync * @remarks See remarks on RTReqPoolCallEx.
f5edc444546b57af847ae33f2bd1e10442496e47vboxsyncRTDECL(int) RTReqPoolCallVoidNoWait(RTREQPOOL hPool, PFNRT pfnFunction, unsigned cArgs, ...);
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * Retainsa reference to a request.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param hReq The request handle.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * Releases a reference to the request.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * When the reference count reaches zero, the request will be pooled for reuse.
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @returns The new reference count, UINT32_MAX on invalid handle (asserted).
9de47c4ec7b0fc9a384e4b815153de399da7b8devboxsync * @param hReq Package to release.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Queue a request.
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * The quest must be allocated using RTReqQueueAlloc() or RTReqPoolAlloc() and
36411046d85fccaa66061120a064225fd1b5ae01vboxsync * contain all the required data.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * If it's desired to poll on the completion of the request set cMillies
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * to 0 and use RTReqWait() to check for completion. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pReq The request to queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
36411046d85fccaa66061120a064225fd1b5ae01vboxsyncRTDECL(int) RTReqSubmit(PRTREQ pReq, RTMSINTERVAL cMillies);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Wait for a request to be completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pReq The request to wait for.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Use RT_INDEFINITE_WAIT to only wait till it's completed.
b79e4344bf4eb8033fd06d560cd864192728bd0bvboxsyncRTDECL(int) RTReqWait(PRTREQ pReq, RTMSINTERVAL cMillies);
672b9b73c5db0590fa77ef0f26b024d4e61bad86vboxsync * Get the status of the request.
672b9b73c5db0590fa77ef0f26b024d4e61bad86vboxsync * @returns Status code in the IPRT tradition.
672b9b73c5db0590fa77ef0f26b024d4e61bad86vboxsync * @param pReq The request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync#endif /* IN_RING3 */