req.h revision cb13ee8e628d04a773894bf4f9e8047d74f2ee21
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * innotek Portable Runtime - Request packets
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Copyright (C) 2006-2007 innotek GmbH
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * available from http://www.virtualbox.org. This file is free software;
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * you can redistribute it and/or modify it under the terms of the GNU
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * General Public License (GPL) as published by the Free Software
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The contents of this file may alternatively be used under the terms
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * of the Common Development and Distribution License Version 1.0
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * VirtualBox OSE distribution, in which case the provisions of the
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * CDDL are applicable instead of those of the GPL.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * You may elect to license modified versions of this file under the
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * terms and conditions of either the GPL or the CDDL or both.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync/** @defgroup grp_rt_req RTReq - Request Packet Management
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @ingroup grp_rt
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Request type.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Invalid request. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** RT: Internal. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Maximum request type (exclusive). Used for validation. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Request state.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The state is invalid. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request have been allocated and is in the process of being filed. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request is queued by the requester. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request is begin processed. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request is completed, the requester is begin notified. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request packet is in the free chain. (The requester */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Request flags.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request returns a iprt status code. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The request is a void request and have no status code. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Return type mask. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Caller does not wait on the packet, Queue process thread will free it. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync/** Pointer to a request queue. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * RT Request packet.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * This is used to request an action in the queue handler thread.
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsynctypedef struct RTREQ
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Pointer to the next request in the chain. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Pointer to the queue this packet belongs to. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Request state. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** iprt status code for the completed request. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync volatile int iStatus;
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Requester event sem.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The request can use this event semaphore to wait/poll for completion
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * of the request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Set if the event semaphore is clear. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync volatile bool fEventSemClear;
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Flags, RTREQ_FLAGS_*. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Request type. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Request specific data. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** RTREQTYPE_INTERNAL. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Pointer to the function to be called. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Number of arguments. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Array of arguments. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync/** Pointer to an RT request packet. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync/** @todo hide this */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsynctypedef struct RTREQQUEUE
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync /** Head of the request queue. Atomic. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** The last index used during alloc/free. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Number of free request packets. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Array of pointers to lists of free request packets. Atomic. */
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync /** Requester event sem.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The request can use this event semaphore to wait/poll for new requests.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Create a request packet queueu
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ppQueue Where to store the request queue pointer.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Destroy a request packet queueu
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync * @returns iprt status code.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Process one or more request packets
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being added.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cMillies Number of milliseconds to wait for a pending request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Use RT_INDEFINITE_WAIT to only wait till one is added.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsyncRTDECL(int) RTReqProcess(PRTREQQUEUE pQueue, unsigned cMillies);
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Allocate and queue a call request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * If it's desired to poll on the completion of the request set cMillies
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * use RT_INDEFINITE_WAIT.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The returned request packet must be freed using RTReqFree().
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt statuscode.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Will not return VERR_INTERRUPTED.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ppReq Where to store the pointer to the request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * This will be NULL or a valid request pointer not matter what happends.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cMillies Number of milliseconds to wait for the request to
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * wait till it's completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pfnFunction Pointer to the function to call.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cArgs Number of arguments following in the ellipsis.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Not possible to pass 64-bit arguments!
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ... Function arguments.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsyncRTDECL(int) RTReqCall(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Allocate and queue a call request to a void function.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * If it's desired to poll on the completion of the request set cMillies
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * use RT_INDEFINITE_WAIT.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The returned request packet must be freed using RTReqFree().
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Will not return VERR_INTERRUPTED.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ppReq Where to store the pointer to the request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * This will be NULL or a valid request pointer not matter what happends.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cMillies Number of milliseconds to wait for the request to
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * wait till it's completed.
50f998bb47f333d10515d4c12ad01a4e92a0747bvboxsync * @param pfnFunction Pointer to the function to call.
50f998bb47f333d10515d4c12ad01a4e92a0747bvboxsync * @param cArgs Number of arguments following in the ellipsis.
50f998bb47f333d10515d4c12ad01a4e92a0747bvboxsync * Not possible to pass 64-bit arguments!
50f998bb47f333d10515d4c12ad01a4e92a0747bvboxsync * @param ... Function arguments.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsyncRTDECL(int) RTReqCallVoid(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Allocate and queue a call request to a void function.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * If it's desired to poll on the completion of the request set cMillies
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * use RT_INDEFINITE_WAIT.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The returned request packet must be freed using RTReqFree().
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Will not return VERR_INTERRUPTED.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ppReq Where to store the pointer to the request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * This will be NULL or a valid request pointer not matter what happends, unless fFlags
81cfcb51c89626fd5d331d92dcec81c94a5e9d2fvboxsync * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cMillies Number of milliseconds to wait for the request to
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * wait till it's completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param fFlags A combination of the RTREQFLAGS values.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pfnFunction Pointer to the function to call.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cArgs Number of arguments following in the ellipsis.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Not possible to pass 64-bit arguments!
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ... Function arguments.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsyncRTDECL(int) RTReqCallEx(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Allocate and queue a call request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * If it's desired to poll on the completion of the request set cMillies
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * use RT_INDEFINITE_WAIT.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The returned request packet must be freed using RTReqFree().
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Will not return VERR_INTERRUPTED.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ppReq Where to store the pointer to the request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * This will be NULL or a valid request pointer not matter what happends, unless fFlags
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cMillies Number of milliseconds to wait for the request to
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * wait till it's completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param fFlags A combination of the RTREQFLAGS values.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pfnFunction Pointer to the function to call.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param cArgs Number of arguments following in the ellipsis.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Not possible to pass 64-bit arguments!
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param Args Variable argument vector.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsyncRTDECL(int) RTReqCallV(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * Allocates a request packet.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The caller allocates a request packet, fills in the request data
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * union and queues the request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pQueue The request queue.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param ppReq Where to store the pointer to the allocated packet.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param enmType Package type.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsyncRTDECL(int) RTReqAlloc(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTREQTYPE enmType);
e2bd93b4f9c38c9b01eb960ba7bc1fc9c4d38ce8vboxsync * Free a request packet.
e2bd93b4f9c38c9b01eb960ba7bc1fc9c4d38ce8vboxsync * @returns iprt status code.
f091ce66ee934d599f16056078a9a76d7286b959vboxsync * @param pReq Package to free.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @remark The request packet must be in allocated or completed state!
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync * Queue a request.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * The quest must be allocated using RTReqAlloc() and contain
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * all the required data.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * If it's disired to poll on the completion of the request set cMillies
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * use RT_INDEFINITE_WAIT.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns iprt status code.
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync * Will not return VERR_INTERRUPTED.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
0b74a2f80aba476dc8be8bc1c63891fc53945986vboxsync * @param pReq The request to queue.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * @param cMillies Number of milliseconds to wait for the request to
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * be completed. Use RT_INDEFINITE_WAIT to only
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * wait till it's completed.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsyncRTDECL(int) RTReqQueue(PRTREQ pReq, unsigned cMillies);
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * Wait for a request to be completed.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * @returns iprt status code.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * Will not return VERR_INTERRUPTED.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * @param pReq The request to wait for.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * @param cMillies Number of milliseconds to wait.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync * Use RT_INDEFINITE_WAIT to only wait till it's completed.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsyncRTDECL(int) RTReqWait(PRTREQ pReq, unsigned cMillies);
d1d4bf58f99da14d0aaa7bcc728a359c8a7eb7bdvboxsync#endif /* IN_RING3 */