[39499] | 1 | /* $Id: req.h 98103 2023-01-17 14:15:46Z vboxsync $ */
|
---|
| 2 | /** @file
|
---|
| 3 | * IPRT - Internal RTReq header.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[98103] | 7 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[39499] | 8 | *
|
---|
[96407] | 9 | * This file is part of VirtualBox base platform packages, as
|
---|
| 10 | * available from https://www.virtualbox.org.
|
---|
[39499] | 11 | *
|
---|
[96407] | 12 | * This program is free software; you can redistribute it and/or
|
---|
| 13 | * modify it under the terms of the GNU General Public License
|
---|
| 14 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 15 | * License.
|
---|
| 16 | *
|
---|
| 17 | * This program is distributed in the hope that it will be useful, but
|
---|
| 18 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 19 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 20 | * General Public License for more details.
|
---|
| 21 | *
|
---|
| 22 | * You should have received a copy of the GNU General Public License
|
---|
| 23 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 24 | *
|
---|
[39499] | 25 | * The contents of this file may alternatively be used under the terms
|
---|
| 26 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 27 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 28 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[39499] | 29 | * CDDL are applicable instead of those of the GPL.
|
---|
| 30 | *
|
---|
| 31 | * You may elect to license modified versions of this file under the
|
---|
| 32 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 33 | *
|
---|
| 34 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[39499] | 35 | */
|
---|
| 36 |
|
---|
[76559] | 37 | #ifndef IPRT_INCLUDED_INTERNAL_req_h
|
---|
| 38 | #define IPRT_INCLUDED_INTERNAL_req_h
|
---|
[76513] | 39 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 40 | # pragma once
|
---|
| 41 | #endif
|
---|
[39499] | 42 |
|
---|
| 43 | #include <iprt/types.h>
|
---|
| 44 |
|
---|
[39504] | 45 |
|
---|
[39499] | 46 | RT_C_DECLS_BEGIN
|
---|
| 47 |
|
---|
| 48 | /**
|
---|
[39504] | 49 | * Request state.
|
---|
| 50 | */
|
---|
| 51 | typedef enum RTREQSTATE
|
---|
| 52 | {
|
---|
| 53 | /** The state is invalid. */
|
---|
| 54 | RTREQSTATE_INVALID = 0,
|
---|
| 55 | /** The request have been allocated and is in the process of being filed. */
|
---|
| 56 | RTREQSTATE_ALLOCATED,
|
---|
| 57 | /** The request is queued by the requester. */
|
---|
| 58 | RTREQSTATE_QUEUED,
|
---|
| 59 | /** The request is begin processed. */
|
---|
| 60 | RTREQSTATE_PROCESSING,
|
---|
[88813] | 61 | /** The request has been cancelled. */
|
---|
| 62 | RTREQSTATE_CANCELLED,
|
---|
[39504] | 63 | /** The request is completed, the requester is begin notified. */
|
---|
| 64 | RTREQSTATE_COMPLETED,
|
---|
[88813] | 65 | /** The request packet is in the free chain. */
|
---|
[39504] | 66 | RTREQSTATE_FREE
|
---|
| 67 | } RTREQSTATE;
|
---|
[88813] | 68 | AssertCompileSize(RTREQSTATE, sizeof(uint32_t));
|
---|
[39504] | 69 |
|
---|
| 70 |
|
---|
| 71 | /**
|
---|
| 72 | * RT Request packet.
|
---|
| 73 | *
|
---|
| 74 | * This is used to request an action in the queue handler thread.
|
---|
| 75 | */
|
---|
| 76 | struct RTREQ
|
---|
| 77 | {
|
---|
| 78 | /** Magic number (RTREQ_MAGIC). */
|
---|
| 79 | uint32_t u32Magic;
|
---|
| 80 | /** Set if the event semaphore is clear. */
|
---|
| 81 | volatile bool fEventSemClear;
|
---|
[39550] | 82 | /** Set if the push back semaphore should be signaled when the request
|
---|
| 83 | * is picked up from the queue. */
|
---|
| 84 | volatile bool fSignalPushBack;
|
---|
[39504] | 85 | /** Set if pool, clear if queue. */
|
---|
| 86 | volatile bool fPoolOrQueue;
|
---|
| 87 | /** IPRT status code for the completed request. */
|
---|
| 88 | volatile int32_t iStatusX;
|
---|
| 89 | /** Request state. */
|
---|
| 90 | volatile RTREQSTATE enmState;
|
---|
[39550] | 91 | /** The reference count. */
|
---|
| 92 | volatile uint32_t cRefs;
|
---|
[39504] | 93 |
|
---|
| 94 | /** Pointer to the next request in the chain. */
|
---|
| 95 | struct RTREQ * volatile pNext;
|
---|
| 96 |
|
---|
| 97 | union
|
---|
| 98 | {
|
---|
| 99 | /** Pointer to the pool this packet belongs to. */
|
---|
| 100 | RTREQPOOL hPool;
|
---|
| 101 | /** Pointer to the queue this packet belongs to. */
|
---|
| 102 | RTREQQUEUE hQueue;
|
---|
[39550] | 103 | /** Opaque owner access. */
|
---|
| 104 | void *pv;
|
---|
[39504] | 105 | } uOwner;
|
---|
| 106 |
|
---|
[39517] | 107 | /** Timestamp take when the request was submitted to a pool. Not used
|
---|
| 108 | * for queued request. */
|
---|
| 109 | uint64_t uSubmitNanoTs;
|
---|
[39545] | 110 | /** Requester completion event sem. */
|
---|
[39504] | 111 | RTSEMEVENT EventSem;
|
---|
[39545] | 112 | /** Request pushback event sem. Allocated lazily. */
|
---|
| 113 | RTSEMEVENTMULTI hPushBackEvt;
|
---|
[39504] | 114 | /** Flags, RTREQ_FLAGS_*. */
|
---|
| 115 | uint32_t fFlags;
|
---|
| 116 | /** Request type. */
|
---|
| 117 | RTREQTYPE enmType;
|
---|
| 118 | /** Request specific data. */
|
---|
| 119 | union RTREQ_U
|
---|
| 120 | {
|
---|
| 121 | /** RTREQTYPE_INTERNAL. */
|
---|
| 122 | struct
|
---|
| 123 | {
|
---|
| 124 | /** Pointer to the function to be called. */
|
---|
| 125 | PFNRT pfn;
|
---|
| 126 | /** Number of arguments. */
|
---|
| 127 | uint32_t cArgs;
|
---|
| 128 | /** Array of arguments. */
|
---|
[88813] | 129 | uintptr_t aArgs[12];
|
---|
[39504] | 130 | } Internal;
|
---|
| 131 | } u;
|
---|
| 132 | };
|
---|
| 133 |
|
---|
[39510] | 134 | /** Internal request representation. */
|
---|
| 135 | typedef RTREQ RTREQINT;
|
---|
| 136 | /** Pointer to an internal request representation. */
|
---|
| 137 | typedef RTREQINT *PRTREQINT;
|
---|
[39504] | 138 |
|
---|
| 139 | /**
|
---|
[39499] | 140 | * Internal queue instance.
|
---|
| 141 | */
|
---|
| 142 | typedef struct RTREQQUEUEINT
|
---|
| 143 | {
|
---|
[39500] | 144 | /** Magic value (RTREQQUEUE_MAGIC). */
|
---|
| 145 | uint32_t u32Magic;
|
---|
| 146 | /** Set if busy (pending or processing requests). */
|
---|
| 147 | bool volatile fBusy;
|
---|
[60121] | 148 | /** Head of the request queue (LIFO). Atomic. */
|
---|
[39499] | 149 | volatile PRTREQ pReqs;
|
---|
[60121] | 150 | /** List of requests pending after a non-VINF_SUCCESS status code forced
|
---|
| 151 | * RTReqQueueProcess to stop processing requestins. This is in FIFO order. */
|
---|
| 152 | volatile PRTREQ pAlreadyPendingReqs;
|
---|
[39499] | 153 | /** The last index used during alloc/free. */
|
---|
| 154 | volatile uint32_t iReqFree;
|
---|
| 155 | /** Number of free request packets. */
|
---|
| 156 | volatile uint32_t cReqFree;
|
---|
| 157 | /** Array of pointers to lists of free request packets. Atomic. */
|
---|
| 158 | volatile PRTREQ apReqFree[9];
|
---|
| 159 | /** Requester event sem.
|
---|
| 160 | * The request can use this event semaphore to wait/poll for new requests.
|
---|
| 161 | */
|
---|
| 162 | RTSEMEVENT EventSem;
|
---|
| 163 | } RTREQQUEUEINT;
|
---|
| 164 |
|
---|
| 165 | /** Pointer to an internal queue instance. */
|
---|
[39550] | 166 | typedef struct RTREQQUEUEINT *PRTREQQUEUEINT;
|
---|
| 167 | /** Pointer to a request thread pool instance. */
|
---|
| 168 | typedef struct RTREQPOOLINT *PRTREQPOOLINT;
|
---|
[39499] | 169 |
|
---|
| 170 |
|
---|
[39550] | 171 | /* req.cpp */
|
---|
| 172 | DECLHIDDEN(int) rtReqAlloc(RTREQTYPE enmType, bool fPoolOrQueue, void *pvOwner, PRTREQ *phReq);
|
---|
| 173 | DECLHIDDEN(int) rtReqReInit(PRTREQINT pReq, RTREQTYPE enmType);
|
---|
| 174 | DECLHIDDEN(void) rtReqFreeIt(PRTREQINT pReq);
|
---|
| 175 | DECLHIDDEN(int) rtReqProcessOne(PRTREQ pReq);
|
---|
[39500] | 176 |
|
---|
[39550] | 177 | /* reqpool.cpp / reqqueue.cpp. */
|
---|
| 178 | DECLHIDDEN(void) rtReqQueueSubmit(PRTREQQUEUEINT pQueue, PRTREQINT pReq);
|
---|
| 179 | DECLHIDDEN(void) rtReqPoolSubmit(PRTREQPOOLINT pPool, PRTREQINT pReq);
|
---|
[88813] | 180 | DECLHIDDEN(void) rtReqPoolCancel(PRTREQPOOLINT pPool, PRTREQINT pReq);
|
---|
[39550] | 181 | DECLHIDDEN(bool) rtReqQueueRecycle(PRTREQQUEUEINT pQueue, PRTREQINT pReq);
|
---|
| 182 | DECLHIDDEN(bool) rtReqPoolRecycle(PRTREQPOOLINT pPool, PRTREQINT pReq);
|
---|
[39500] | 183 |
|
---|
[39499] | 184 | RT_C_DECLS_END
|
---|
| 185 |
|
---|
[76585] | 186 | #endif /* !IPRT_INCLUDED_INTERNAL_req_h */
|
---|
[39499] | 187 |
|
---|