StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
byte_budget.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Buffer.
5 *
6 * StormByte-Buffer original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Buffer source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, and in particular the bundled StormByte-Logger tree and
23 * the rest of the StormByte suite it vendors), which remains under its own
24 * license.
25 *
26 * Neither license grants any patent rights. Any patent licenses required
27 * to use this software or third-party components must be obtained separately
28 * from the patent holders.
29 *
30 * StormByte-Buffer is distributed in the hope that it will be useful,
31 * but WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 * GNU Lesser General Public License for more details.
34 *
35 * You should have received a copy of the GNU Lesser General Public License
36 * version 3 along with StormByte-Buffer. If not, see
37 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
38 *
39 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
40 */
41
42#pragma once
43
45#include <StormByte/byte_size.hxx>
46#include <StormByte/safe/optional.hxx>
47#include <StormByte/safe/pointers.hxx>
48#include <StormByte/size.hxx>
49#include <StormByte/type_traits/safe.hxx>
50
51#include <chrono>
52#include <cstddef>
53#include <cstdint>
54#include <optional>
55
60namespace StormByte {
65 namespace Buffer {
70 namespace Detail {
74 struct BudgetAccess;
75 }
76
92
100
118 void* Context = nullptr;
119 void (*Changed)(void*, AdmissionWaitReason, bool entering) noexcept = nullptr;
120 };
121
126 public:
135 m_elements_limited(elements.has_value()),
136 m_bytes_limited(bytes.has_value()),
137 m_elements(elements.value_or(StormByte::Size{0})),
138 m_bytes(bytes.value_or(StormByte::ByteSize{0})) {}
139
144 QueueLimits(const QueueLimits& other) noexcept = default;
145
150 QueueLimits(QueueLimits&& other) noexcept = default;
151
155 ~QueueLimits() noexcept = default;
156
162 QueueLimits& operator=(const QueueLimits& other) noexcept = default;
163
169 QueueLimits& operator=(QueueLimits&& other) noexcept = default;
170
175 constexpr bool ElementsLimited() const noexcept { return m_elements_limited; }
176
181 constexpr bool BytesLimited() const noexcept { return m_bytes_limited; }
182
187 constexpr StormByte::Size Elements() const noexcept { return m_elements; }
188
193 constexpr void Elements(StormByte::Size elements) noexcept {
194 m_elements = elements;
195 m_elements_limited = true;
196 }
197
201 constexpr void UnlimitedElements() noexcept {
202 m_elements_limited = false;
203 m_elements = StormByte::Size{0};
204 }
205
210 constexpr StormByte::ByteSize Bytes() const noexcept { return m_bytes; }
211
212 private:
213 bool m_elements_limited;
214 bool m_bytes_limited;
215 StormByte::Size m_elements;
216 StormByte::ByteSize m_bytes;
217 };
218
234
239 bool Limited {false};
243 std::size_t Pressure {0};
244 std::size_t Waits {0};
245 std::int64_t WaitNanoseconds {0};
246 bool Closed {false};
247 };
248
257 public:
262 public:
266 Lease() noexcept = default;
267
272 Lease(const Lease& other) noexcept = default;
273
278 Lease(Lease&& other) noexcept = default;
279
283 ~Lease() noexcept = default;
284
290 Lease& operator=(const Lease& other) noexcept = default;
291
297 Lease& operator=(Lease&& other) noexcept = default;
298
303 explicit operator bool() const noexcept;
304
309 StormByte::ByteSize Bytes() const noexcept;
310
316 bool BelongsTo(const ByteBudget& budget) const noexcept;
317
321 void Reset() noexcept;
322
323 private:
324 friend class ByteBudget;
325
329 struct Charge;
330
331 StormByte::Safe::Shared<Charge> m_charge;
332 };
333
338
342 STORMBYTE_FORCE_INLINE explicit ByteBudget(std::nullopt_t): ByteBudget() {}
343
348 explicit ByteBudget(StormByte::ByteSize limit): ByteBudget(true, limit) {}
349
354 ByteBudget(const ByteBudget& other) noexcept = default;
355
360 ByteBudget(ByteBudget&& other) noexcept = default;
361
365 ~ByteBudget() noexcept = default;
366
372 ByteBudget& operator=(const ByteBudget& other) noexcept = default;
373
379 ByteBudget& operator=(ByteBudget&& other) noexcept = default;
380
387 QueueStatus TryReserve(StormByte::ByteSize bytes, Lease& output) const noexcept;
388
397 std::chrono::milliseconds timeout) const noexcept {
398 return ReserveMilliseconds(bytes, output, timeout.count());
399 }
400
404 void Close() const noexcept;
405
409 void CancelPending() const noexcept;
410
420 bool SharesIdentity(const ByteBudget& other) const noexcept;
421
426 BudgetSnapshot Snapshot() const noexcept;
427
428 private:
429 friend struct Detail::BudgetAccess;
430
434 struct State;
435
439 struct Event {
440 std::size_t Revision;
441 std::size_t Cancellation;
442 };
443
449 ByteBudget(bool limited, StormByte::ByteSize limit);
450
455 Event CurrentEvent() const noexcept;
456
460 void Notify() const noexcept;
461
467 void Wait(Event event, std::int64_t nanoseconds) const noexcept;
468
476 QueueStatus ReserveMilliseconds(StormByte::ByteSize bytes, Lease& output,
477 std::int64_t milliseconds) const noexcept;
478
479 StormByte::Safe::Shared<State> m_state;
480 };
481
486 namespace Detail {
496 static auto Event(const ByteBudget& budget) noexcept { return budget.CurrentEvent(); }
497
502 static void Notify(const ByteBudget& budget) noexcept { budget.Notify(); }
503
510 static void Wait(const ByteBudget& budget, ByteBudget::Event event,
511 std::int64_t nanoseconds) noexcept {
512 budget.Wait(event, nanoseconds);
513 }
514 };
515 }
516 }
517}
518
Shared charge that can explicitly follow one payload across queues or work.
Definition byte_budget.hxx:261
StormByte::ByteSize Bytes() const noexcept
Size reserved once for all copies.
bool BelongsTo(const ByteBudget &budget) const noexcept
Check shared budget identity.
friend class ByteBudget
Definition byte_budget.hxx:324
void Reset() noexcept
Release this reference.
Lease() noexcept=default
Construct an empty charge.
Shared logical byte accounting for queues and concurrent work.
Definition byte_budget.hxx:256
bool SharesIdentity(const ByteBudget &other) const noexcept
Compare shared provider state without reserving or locking.
void Close() const noexcept
Reject future reservations and wake waiters, retaining existing charges.
QueueStatus TryReserve(StormByte::ByteSize bytes, Lease &output) const noexcept
Reserve without waiting for capacity.
~ByteBudget() noexcept=default
Release this handle without closing other handles or leases.
STORMBYTE_FORCE_INLINE QueueStatus ReserveFor(StormByte::ByteSize bytes, Lease &output, std::chrono::milliseconds timeout) const noexcept
Reserve with a bounded wait; zero attempts immediately.
Definition byte_budget.hxx:396
STORMBYTE_FORCE_INLINE ByteBudget(std::nullopt_t)
Explicitly construct an unlimited budget.
Definition byte_budget.hxx:342
ByteBudget()
Construct an unlimited aggregate budget.
Definition byte_budget.hxx:337
BudgetSnapshot Snapshot() const noexcept
Read counters under a short state lock, without capacity waits or I/O.
void CancelPending() const noexcept
Cancel currently waiting admissions without closing or invalidating leases.
ByteBudget(const ByteBudget &other) noexcept=default
Share budget identity and counters.
friend struct Detail::BudgetAccess
Definition byte_budget.hxx:429
ByteBudget(ByteBudget &&other) noexcept=default
Transfer a budget handle.
ByteBudget(StormByte::ByteSize limit)
Construct a fixed aggregate ceiling; zero allows only zero-byte charges.
Definition byte_budget.hxx:348
General exception for buffer errors.
Definition exception.hxx:166
Independent local bounds; absent means unlimited, engaged zero means zero capacity.
Definition byte_budget.hxx:125
QueueLimits(QueueLimits &&other) noexcept=default
Move resolved bounds without ownership.
constexpr StormByte::ByteSize Bytes() const noexcept
Configured byte ceiling.
Definition byte_budget.hxx:210
constexpr StormByte::Size Elements() const noexcept
Configured item ceiling.
Definition byte_budget.hxx:187
constexpr bool BytesLimited() const noexcept
Whether a byte ceiling is configured.
Definition byte_budget.hxx:181
constexpr void Elements(StormByte::Size elements) noexcept
Engage an item ceiling without allocating an optional.
Definition byte_budget.hxx:193
~QueueLimits() noexcept=default
Destroy non-owning bounds.
QueueLimits(const QueueLimits &other) noexcept=default
Copy resolved bounds without allocation.
STORMBYTE_FORCE_INLINE QueueLimits(StormByte::Safe::Optional< StormByte::Size > elements={}, StormByte::Safe::Optional< StormByte::ByteSize > bytes={}) noexcept
Resolve optional limits into a non-owning value.
Definition byte_budget.hxx:132
constexpr bool ElementsLimited() const noexcept
Whether an item ceiling is configured.
Definition byte_budget.hxx:175
constexpr void UnlimitedElements() noexcept
Remove only the item ceiling without changing byte limits.
Definition byte_budget.hxx:201
STORMBYTE_DECLARE_MAYBE_SAFE(class StormByte::System::Device::Access)
Buffer module of the StormByte suite.
QueueStatus
Admission outcomes.
Definition byte_budget.hxx:80
@ Closed
Queue, Sink or budget closed.
Definition byte_budget.hxx:84
@ Missing
Sink key does not exist.
Definition byte_budget.hxx:87
@ Invalid
Invalid duration, lease or configuration.
Definition byte_budget.hxx:90
@ TooLarge
The item can never fit the configured limit.
Definition byte_budget.hxx:83
@ Cancelled
Pending admissions cancelled.
Definition byte_budget.hxx:85
@ Ok
Accepted.
Definition byte_budget.hxx:81
@ Timeout
Bounded wait expired.
Definition byte_budget.hxx:86
@ Empty
Nullable item was empty.
Definition byte_budget.hxx:88
@ WouldBlock
Capacity unavailable.
Definition byte_budget.hxx:82
AdmissionWaitReason
Cause of a weighted admission wait, selected while admission is locked.
Definition byte_budget.hxx:96
@ LocalCapacity
Local element or byte bounds deny admission before reservation.
Definition byte_budget.hxx:97
@ SharedBudget
Local bounds allow admission but TryReserve reports WouldBlock.
Definition byte_budget.hxx:98
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Borrowed, allocation-free observer for one synchronous PushFor call.
Definition byte_budget.hxx:117
void(* Changed)(void *, AdmissionWaitReason, bool entering) noexcept
Wait transition.
Definition byte_budget.hxx:119
void * Context
Borrowed callback context.
Definition byte_budget.hxx:118
Shared reservation counters, independent of any particular queue.
Definition byte_budget.hxx:238
std::size_t Pressure
Reservations refused for temporary capacity pressure.
Definition byte_budget.hxx:243
std::size_t Waits
ReserveFor calls that actually waited.
Definition byte_budget.hxx:244
std::int64_t WaitNanoseconds
Accumulated ReserveFor wait duration.
Definition byte_budget.hxx:245
StormByte::ByteSize Limit
Configured aggregate ceiling.
Definition byte_budget.hxx:240
bool Limited
Aggregate ceiling is active.
Definition byte_budget.hxx:239
StormByte::ByteSize Reserved
Live lease charges, including work outside queues.
Definition byte_budget.hxx:241
bool Closed
Further reservations are forbidden.
Definition byte_budget.hxx:246
StormByte::ByteSize Peak
Lifetime peak reservations.
Definition byte_budget.hxx:242
Queue wake transport; never calls into queues under the budget mutex.
Definition byte_budget.hxx:490
static void Wait(const ByteBudget &budget, ByteBudget::Event event, std::int64_t nanoseconds) noexcept
Wait for state changes without holding queue locks.
Definition byte_budget.hxx:510
static void Notify(const ByteBudget &budget) noexcept
Publish a queue state change.
Definition byte_budget.hxx:502
static auto Event(const ByteBudget &budget) noexcept
Capture a stored event.
Definition byte_budget.hxx:496
Coherent queue accounting; bytes are caller-supplied weights, never RSS.
Definition byte_budget.hxx:222
std::size_t Waits
Admissions that actually waited.
Definition byte_budget.hxx:229
bool Closed
Production has ended.
Definition byte_budget.hxx:231
StormByte::ByteSize PeakBytes
Lifetime peak logical bytes.
Definition byte_budget.hxx:227
StormByte::ByteSize Bytes
Currently queued logical weights.
Definition byte_budget.hxx:225
bool Exists
False for a missing Sink key.
Definition byte_budget.hxx:232
QueueLimits Limits
Configured local bounds.
Definition byte_budget.hxx:223
std::size_t Pressure
Admissions encountering capacity pressure.
Definition byte_budget.hxx:228
std::int64_t WaitNanoseconds
Accumulated admission wait duration.
Definition byte_budget.hxx:230
StormByte::Size Elements
Currently queued entries.
Definition byte_budget.hxx:224
StormByte::Size PeakElements
Lifetime peak entries.
Definition byte_budget.hxx:226
#define STORMBYTE_BUFFER_PUBLIC
Definition visibility.h:54