| | | 1 | | //======================================================================= |
| | | 2 | | // NavigationQueryLimits.cs |
| | | 3 | | //======================================================================= |
| | | 4 | | // MIT License, Copyright (c) 2024-present David Oravsky (mrdav30) |
| | | 5 | | // See LICENSE file in the project root for full license information. |
| | | 6 | | //======================================================================= |
| | | 7 | | |
| | | 8 | | namespace Trailblazer.Pathing; |
| | | 9 | | |
| | | 10 | | /// <summary>Defines finite context-owned navigation query admission and retention ceilings.</summary> |
| | | 11 | | public readonly struct NavigationQueryLimits |
| | | 12 | | { |
| | | 13 | | /// <summary>The hard ceiling for one deterministic query batch.</summary> |
| | | 14 | | public const int MaximumBatchItems = 256; |
| | | 15 | | |
| | | 16 | | /// <summary>Gets the recommended finite navigation query limits.</summary> |
| | | 17 | | public static NavigationQueryLimits Default { get; } = new( |
| | | 18 | | maxBatchItems: 8, |
| | | 19 | | maxBatchDescriptorBytes: 65_536, |
| | | 20 | | maxConcurrentNavigationQueries: 8, |
| | | 21 | | aStarWorkspaceMapCapacity: 16, |
| | | 22 | | aStarWorkspaceEndpointPageCapacity: 512, |
| | | 23 | | aStarWorkspaceComponentCapacity: 512, |
| | | 24 | | aStarWorkspaceNodeCapacity: 4_096, |
| | | 25 | | maxAStarCacheEntries: 128, |
| | | 26 | | maxAStarReusablePayloadBytes: 16_777_216, |
| | | 27 | | maxAStarSinglePayloadBytes: 1_159_480, |
| | | 28 | | maxAStarActivePayloadBytes: 4_194_304, |
| | | 29 | | maxAStarActivePayloadLeases: 8, |
| | | 30 | | flowWorkspaceMapCapacity: 16, |
| | | 31 | | flowWorkspaceEndpointPageCapacity: 512, |
| | | 32 | | flowWorkspaceComponentCapacity: 512, |
| | | 33 | | flowWorkspaceNodeCapacity: 4_096, |
| | | 34 | | rayWorkspaceCoveredAddressCapacity: 4_096, |
| | | 35 | | rayWorkspaceTraceIntervalCapacity: 4_096, |
| | | 36 | | aStarWorkspaceGuidePointCapacity: 8_191, |
| | | 37 | | maxFlowCacheEntries: 128, |
| | | 38 | | maxFlowReusablePayloadBytes: 33_554_432, |
| | | 39 | | maxFlowSinglePayloadBytes: 1_012_024, |
| | | 40 | | maxFlowActivePayloadBytes: 4_194_304, |
| | | 41 | | maxFlowActivePayloadLeases: 8); |
| | | 42 | | |
| | | 43 | | /// <summary>Initializes explicit finite navigation query limits.</summary> |
| | | 44 | | public NavigationQueryLimits( |
| | | 45 | | int maxBatchItems, |
| | | 46 | | long maxBatchDescriptorBytes, |
| | | 47 | | int maxConcurrentNavigationQueries, |
| | | 48 | | int aStarWorkspaceMapCapacity, |
| | | 49 | | int aStarWorkspaceEndpointPageCapacity, |
| | | 50 | | int aStarWorkspaceComponentCapacity, |
| | | 51 | | int aStarWorkspaceNodeCapacity, |
| | | 52 | | int maxAStarCacheEntries, |
| | | 53 | | long maxAStarReusablePayloadBytes, |
| | | 54 | | long maxAStarSinglePayloadBytes, |
| | | 55 | | long maxAStarActivePayloadBytes, |
| | | 56 | | int maxAStarActivePayloadLeases, |
| | | 57 | | int flowWorkspaceMapCapacity, |
| | | 58 | | int flowWorkspaceEndpointPageCapacity, |
| | | 59 | | int flowWorkspaceComponentCapacity, |
| | | 60 | | int flowWorkspaceNodeCapacity, |
| | | 61 | | int rayWorkspaceCoveredAddressCapacity, |
| | | 62 | | int rayWorkspaceTraceIntervalCapacity, |
| | | 63 | | int aStarWorkspaceGuidePointCapacity, |
| | | 64 | | int maxFlowCacheEntries, |
| | | 65 | | long maxFlowReusablePayloadBytes, |
| | | 66 | | long maxFlowSinglePayloadBytes, |
| | | 67 | | long maxFlowActivePayloadBytes, |
| | | 68 | | int maxFlowActivePayloadLeases) |
| | | 69 | | { |
| | 89 | 70 | | SwiftThrowHelper.ThrowIfArgumentOutOfRange( |
| | 89 | 71 | | maxBatchItems <= 0 || maxBatchItems > MaximumBatchItems, |
| | 89 | 72 | | maxBatchItems, |
| | 89 | 73 | | nameof(maxBatchItems)); |
| | 87 | 74 | | ThrowIfNonPositive(maxBatchDescriptorBytes, nameof(maxBatchDescriptorBytes)); |
| | 87 | 75 | | ThrowIfNonPositive( |
| | 87 | 76 | | maxConcurrentNavigationQueries, |
| | 87 | 77 | | nameof(maxConcurrentNavigationQueries)); |
| | 86 | 78 | | ValidateWorkspace( |
| | 86 | 79 | | aStarWorkspaceMapCapacity, |
| | 86 | 80 | | aStarWorkspaceEndpointPageCapacity, |
| | 86 | 81 | | aStarWorkspaceComponentCapacity, |
| | 86 | 82 | | aStarWorkspaceNodeCapacity, |
| | 86 | 83 | | nameof(aStarWorkspaceMapCapacity), |
| | 86 | 84 | | nameof(aStarWorkspaceEndpointPageCapacity), |
| | 86 | 85 | | nameof(aStarWorkspaceComponentCapacity), |
| | 86 | 86 | | nameof(aStarWorkspaceNodeCapacity)); |
| | 85 | 87 | | ValidateCache( |
| | 85 | 88 | | maxAStarCacheEntries, |
| | 85 | 89 | | maxAStarReusablePayloadBytes, |
| | 85 | 90 | | maxAStarSinglePayloadBytes, |
| | 85 | 91 | | maxAStarActivePayloadBytes, |
| | 85 | 92 | | maxAStarActivePayloadLeases, |
| | 85 | 93 | | nameof(maxAStarCacheEntries), |
| | 85 | 94 | | nameof(maxAStarReusablePayloadBytes), |
| | 85 | 95 | | nameof(maxAStarSinglePayloadBytes), |
| | 85 | 96 | | nameof(maxAStarActivePayloadBytes), |
| | 85 | 97 | | nameof(maxAStarActivePayloadLeases)); |
| | 85 | 98 | | ValidateWorkspace( |
| | 85 | 99 | | flowWorkspaceMapCapacity, |
| | 85 | 100 | | flowWorkspaceEndpointPageCapacity, |
| | 85 | 101 | | flowWorkspaceComponentCapacity, |
| | 85 | 102 | | flowWorkspaceNodeCapacity, |
| | 85 | 103 | | nameof(flowWorkspaceMapCapacity), |
| | 85 | 104 | | nameof(flowWorkspaceEndpointPageCapacity), |
| | 85 | 105 | | nameof(flowWorkspaceComponentCapacity), |
| | 85 | 106 | | nameof(flowWorkspaceNodeCapacity)); |
| | 84 | 107 | | ThrowIfNonPositive( |
| | 84 | 108 | | rayWorkspaceCoveredAddressCapacity, |
| | 84 | 109 | | nameof(rayWorkspaceCoveredAddressCapacity)); |
| | 83 | 110 | | ThrowIfNonPositive( |
| | 83 | 111 | | rayWorkspaceTraceIntervalCapacity, |
| | 83 | 112 | | nameof(rayWorkspaceTraceIntervalCapacity)); |
| | 82 | 113 | | SwiftThrowHelper.ThrowIfArgument( |
| | 82 | 114 | | rayWorkspaceTraceIntervalCapacity > rayWorkspaceCoveredAddressCapacity, |
| | 82 | 115 | | nameof(rayWorkspaceTraceIntervalCapacity), |
| | 82 | 116 | | "Trace-interval capacity cannot exceed covered-address capacity."); |
| | 81 | 117 | | ThrowIfNonPositive( |
| | 81 | 118 | | aStarWorkspaceGuidePointCapacity, |
| | 81 | 119 | | nameof(aStarWorkspaceGuidePointCapacity)); |
| | 80 | 120 | | SwiftThrowHelper.ThrowIfArgument( |
| | 80 | 121 | | aStarWorkspaceGuidePointCapacity < aStarWorkspaceNodeCapacity, |
| | 80 | 122 | | nameof(aStarWorkspaceGuidePointCapacity), |
| | 80 | 123 | | "A* guide-point capacity must cover every admitted search node."); |
| | 80 | 124 | | ValidateCache( |
| | 80 | 125 | | maxFlowCacheEntries, |
| | 80 | 126 | | maxFlowReusablePayloadBytes, |
| | 80 | 127 | | maxFlowSinglePayloadBytes, |
| | 80 | 128 | | maxFlowActivePayloadBytes, |
| | 80 | 129 | | maxFlowActivePayloadLeases, |
| | 80 | 130 | | nameof(maxFlowCacheEntries), |
| | 80 | 131 | | nameof(maxFlowReusablePayloadBytes), |
| | 80 | 132 | | nameof(maxFlowSinglePayloadBytes), |
| | 80 | 133 | | nameof(maxFlowActivePayloadBytes), |
| | 80 | 134 | | nameof(maxFlowActivePayloadLeases)); |
| | | 135 | | |
| | 80 | 136 | | MaxBatchItems = maxBatchItems; |
| | 80 | 137 | | MaxBatchDescriptorBytes = maxBatchDescriptorBytes; |
| | 80 | 138 | | MaxConcurrentNavigationQueries = maxConcurrentNavigationQueries; |
| | 80 | 139 | | AStarWorkspaceMapCapacity = aStarWorkspaceMapCapacity; |
| | 80 | 140 | | AStarWorkspaceEndpointPageCapacity = aStarWorkspaceEndpointPageCapacity; |
| | 80 | 141 | | AStarWorkspaceComponentCapacity = aStarWorkspaceComponentCapacity; |
| | 80 | 142 | | AStarWorkspaceNodeCapacity = aStarWorkspaceNodeCapacity; |
| | 80 | 143 | | MaxAStarCacheEntries = maxAStarCacheEntries; |
| | 80 | 144 | | MaxAStarReusablePayloadBytes = maxAStarReusablePayloadBytes; |
| | 80 | 145 | | MaxAStarSinglePayloadBytes = maxAStarSinglePayloadBytes; |
| | 80 | 146 | | MaxAStarActivePayloadBytes = maxAStarActivePayloadBytes; |
| | 80 | 147 | | MaxAStarActivePayloadLeases = maxAStarActivePayloadLeases; |
| | 80 | 148 | | FlowWorkspaceMapCapacity = flowWorkspaceMapCapacity; |
| | 80 | 149 | | FlowWorkspaceEndpointPageCapacity = flowWorkspaceEndpointPageCapacity; |
| | 80 | 150 | | FlowWorkspaceComponentCapacity = flowWorkspaceComponentCapacity; |
| | 80 | 151 | | FlowWorkspaceNodeCapacity = flowWorkspaceNodeCapacity; |
| | 80 | 152 | | RayWorkspaceCoveredAddressCapacity = rayWorkspaceCoveredAddressCapacity; |
| | 80 | 153 | | RayWorkspaceTraceIntervalCapacity = rayWorkspaceTraceIntervalCapacity; |
| | 80 | 154 | | AStarWorkspaceGuidePointCapacity = aStarWorkspaceGuidePointCapacity; |
| | 80 | 155 | | MaxFlowCacheEntries = maxFlowCacheEntries; |
| | 80 | 156 | | MaxFlowReusablePayloadBytes = maxFlowReusablePayloadBytes; |
| | 80 | 157 | | MaxFlowSinglePayloadBytes = maxFlowSinglePayloadBytes; |
| | 80 | 158 | | MaxFlowActivePayloadBytes = maxFlowActivePayloadBytes; |
| | 80 | 159 | | MaxFlowActivePayloadLeases = maxFlowActivePayloadLeases; |
| | 80 | 160 | | } |
| | | 161 | | |
| | | 162 | | /// <summary>Gets the maximum query descriptors accepted by one batch.</summary> |
| | | 163 | | public int MaxBatchItems { get; } |
| | | 164 | | |
| | | 165 | | /// <summary>Gets the maximum logical bytes accepted for submitted batch descriptors.</summary> |
| | | 166 | | public long MaxBatchDescriptorBytes { get; } |
| | | 167 | | |
| | | 168 | | /// <summary>Gets the aggregate maximum concurrently admitted A* and Flow queries.</summary> |
| | | 169 | | public int MaxConcurrentNavigationQueries { get; } |
| | | 170 | | |
| | | 171 | | /// <summary>Gets the map capacity of each exclusive A* workspace.</summary> |
| | | 172 | | public int AStarWorkspaceMapCapacity { get; } |
| | | 173 | | |
| | | 174 | | /// <summary>Gets the endpoint-page capacity of each exclusive A* workspace.</summary> |
| | | 175 | | public int AStarWorkspaceEndpointPageCapacity { get; } |
| | | 176 | | |
| | | 177 | | /// <summary>Gets the component-dependency capacity of each exclusive A* workspace.</summary> |
| | | 178 | | public int AStarWorkspaceComponentCapacity { get; } |
| | | 179 | | |
| | | 180 | | /// <summary>Gets the node capacity of each exclusive A* workspace.</summary> |
| | | 181 | | public int AStarWorkspaceNodeCapacity { get; } |
| | | 182 | | |
| | | 183 | | /// <summary>Gets the maximum reusable A* payload count.</summary> |
| | | 184 | | public int MaxAStarCacheEntries { get; } |
| | | 185 | | |
| | | 186 | | /// <summary>Gets the maximum reusable A* payload bytes.</summary> |
| | | 187 | | public long MaxAStarReusablePayloadBytes { get; } |
| | | 188 | | |
| | | 189 | | /// <summary>Gets the maximum bytes retained by one A* payload.</summary> |
| | | 190 | | public long MaxAStarSinglePayloadBytes { get; } |
| | | 191 | | |
| | | 192 | | /// <summary>Gets the maximum bytes retained by active A* payloads.</summary> |
| | | 193 | | public long MaxAStarActivePayloadBytes { get; } |
| | | 194 | | |
| | | 195 | | /// <summary>Gets the maximum active and reserved A* payload lease count.</summary> |
| | | 196 | | public int MaxAStarActivePayloadLeases { get; } |
| | | 197 | | |
| | | 198 | | /// <summary>Gets the map capacity of each exclusive Flow workspace.</summary> |
| | | 199 | | public int FlowWorkspaceMapCapacity { get; } |
| | | 200 | | |
| | | 201 | | /// <summary>Gets the endpoint and dependency-page capacity of each exclusive Flow workspace.</summary> |
| | | 202 | | public int FlowWorkspaceEndpointPageCapacity { get; } |
| | | 203 | | |
| | | 204 | | /// <summary>Gets the component-dependency capacity of each exclusive Flow workspace.</summary> |
| | | 205 | | public int FlowWorkspaceComponentCapacity { get; } |
| | | 206 | | |
| | | 207 | | /// <summary>Gets the node capacity of each exclusive Flow workspace.</summary> |
| | | 208 | | public int FlowWorkspaceNodeCapacity { get; } |
| | | 209 | | |
| | | 210 | | /// <summary>Gets the covered-address capacity of each navigation-ray workspace.</summary> |
| | | 211 | | public int RayWorkspaceCoveredAddressCapacity { get; } |
| | | 212 | | |
| | | 213 | | /// <summary>Gets the ordered trace-interval capacity of each navigation-ray workspace.</summary> |
| | | 214 | | public int RayWorkspaceTraceIntervalCapacity { get; } |
| | | 215 | | |
| | | 216 | | /// <summary>Gets the raw and simplified guide-point capacity of each A* workspace.</summary> |
| | | 217 | | public int AStarWorkspaceGuidePointCapacity { get; } |
| | | 218 | | |
| | | 219 | | /// <summary>Gets the maximum reusable Flow payload count.</summary> |
| | | 220 | | public int MaxFlowCacheEntries { get; } |
| | | 221 | | |
| | | 222 | | /// <summary>Gets the maximum reusable Flow payload bytes.</summary> |
| | | 223 | | public long MaxFlowReusablePayloadBytes { get; } |
| | | 224 | | |
| | | 225 | | /// <summary>Gets the maximum bytes retained by one Flow payload.</summary> |
| | | 226 | | public long MaxFlowSinglePayloadBytes { get; } |
| | | 227 | | |
| | | 228 | | /// <summary>Gets the maximum bytes retained by unique active Flow payloads.</summary> |
| | | 229 | | public long MaxFlowActivePayloadBytes { get; } |
| | | 230 | | |
| | | 231 | | /// <summary>Gets the maximum active and reserved Flow payload lease count.</summary> |
| | | 232 | | public int MaxFlowActivePayloadLeases { get; } |
| | | 233 | | |
| | | 234 | | private static void ValidateWorkspace( |
| | | 235 | | int mapCapacity, |
| | | 236 | | int pageCapacity, |
| | | 237 | | int componentCapacity, |
| | | 238 | | int nodeCapacity, |
| | | 239 | | string mapName, |
| | | 240 | | string pageName, |
| | | 241 | | string componentName, |
| | | 242 | | string nodeName) |
| | | 243 | | { |
| | 171 | 244 | | SwiftThrowHelper.ThrowIfNegative(mapCapacity, mapName); |
| | 171 | 245 | | SwiftThrowHelper.ThrowIfNegative(pageCapacity, pageName); |
| | 171 | 246 | | SwiftThrowHelper.ThrowIfNegative(componentCapacity, componentName); |
| | 169 | 247 | | SwiftThrowHelper.ThrowIfNegative(nodeCapacity, nodeName); |
| | 169 | 248 | | } |
| | | 249 | | |
| | | 250 | | private static void ValidateCache( |
| | | 251 | | int entries, |
| | | 252 | | long reusableBytes, |
| | | 253 | | long singleBytes, |
| | | 254 | | long activeBytes, |
| | | 255 | | int activeLeases, |
| | | 256 | | string entriesName, |
| | | 257 | | string reusableName, |
| | | 258 | | string singleName, |
| | | 259 | | string activeName, |
| | | 260 | | string leaseName) |
| | | 261 | | { |
| | 165 | 262 | | SwiftThrowHelper.ThrowIfNegative(entries, entriesName); |
| | 165 | 263 | | SwiftThrowHelper.ThrowIfArgumentOutOfRange( |
| | 165 | 264 | | reusableBytes < 0, |
| | 165 | 265 | | null, |
| | 165 | 266 | | reusableName); |
| | 165 | 267 | | ThrowIfNonPositive(singleBytes, singleName); |
| | 165 | 268 | | ThrowIfNonPositive(activeBytes, activeName); |
| | 165 | 269 | | SwiftThrowHelper.ThrowIfArgument( |
| | 165 | 270 | | singleBytes > activeBytes, |
| | 165 | 271 | | singleName, |
| | 165 | 272 | | "A single payload cannot exceed the complete active-payload byte ceiling."); |
| | 165 | 273 | | ThrowIfNonPositive(activeLeases, leaseName); |
| | 165 | 274 | | } |
| | | 275 | | |
| | | 276 | | private static void ThrowIfNonPositive(int value, string parameterName) => |
| | 500 | 277 | | SwiftThrowHelper.ThrowIfArgumentOutOfRange(value <= 0, value, parameterName); |
| | | 278 | | |
| | | 279 | | private static void ThrowIfNonPositive(long value, string parameterName) => |
| | 417 | 280 | | SwiftThrowHelper.ThrowIfArgumentOutOfRange(value <= 0, null, parameterName); |
| | | 281 | | } |