StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
hopper.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/safe/atomic.hxx>
46#include <StormByte/safe/condition_variable.hxx>
47#include <StormByte/safe/owner.hxx>
48#include <StormByte/safe/pointers.hxx>
49#include <StormByte/size.hxx>
50#include <StormByte/type_traits.hxx>
51#include <StormByte/type_traits/safe.hxx>
52
53#include <concepts>
54#include <cstddef>
55#include <type_traits>
56#include <utility>
57
62namespace StormByte {
67 namespace Buffer {
72 namespace Detail {
81 template<typename T>
84 (!Type::Const<T>) && (!std::is_volatile_v<T>) &&
85 std::is_nothrow_default_constructible_v<T> && std::is_nothrow_move_constructible_v<T> &&
86 std::is_nothrow_move_assignable_v<T> && std::is_nothrow_destructible_v<T> &&
87 (alignof(T) <= __STDCPP_DEFAULT_NEW_ALIGNMENT__);
88
93 template<HopperValue T>
94 struct HopperEntry {
98 HopperEntry() noexcept = default;
99
100 HopperEntry(const HopperEntry&) = delete;
101
106 HopperEntry(HopperEntry&& other) noexcept = default;
107
111 ~HopperEntry() noexcept = default;
112
113 HopperEntry& operator=(const HopperEntry&) = delete;
114
120 HopperEntry& operator=(HopperEntry&& other) noexcept = default;
121
122 T Item {};
125 };
126 }
127
132 template<Detail::HopperValue T>
133 class Sink;
134
165 template<Detail::HopperValue T>
166 class Hopper {
167 public:
172
177 Hopper() noexcept(false);
178
184 explicit Hopper(StormByte::Size capacity);
185
186 Hopper(const Hopper&) = delete;
187
188 Hopper(Hopper&&) noexcept = delete;
189
193 ~Hopper() noexcept;
194
195 Hopper& operator=(const Hopper&) = delete;
196
197 Hopper& operator=(Hopper&&) noexcept = delete;
198
202
207
212 StormByte::Size Capacity() const noexcept;
213
221 void Capacity(StormByte::Size capacity) noexcept;
222
227 StormByte::Size Size() const noexcept;
228
233 bool Full() const noexcept;
234
239 unsigned Writers() const noexcept;
240
244
249
258 void Push(T item) noexcept;
259
266 QueueStatus TryPush(T& item, StormByte::ByteSize bytes) noexcept;
267
274 QueueStatus TryPush(T& item, const ByteBudget::Lease& lease) noexcept;
275
284 QueueStatus PushFor(T& item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout,
285 AdmissionWaitObserver observer = {}) noexcept;
286
295 QueueStatus PushFor(T& item, const ByteBudget::Lease& lease, std::chrono::milliseconds timeout,
296 AdmissionWaitObserver observer = {}) noexcept;
297
302 void Limits(QueueLimits limits) noexcept;
303
310 QueueStatus Configure(QueueLimits limits, const ByteBudget& budget) noexcept;
311
316 QueueSnapshot Snapshot() const noexcept;
317
321 void CancelPending() noexcept;
322
326 void Abort() noexcept;
327
333 Hopper& operator<<(T item) noexcept;
334
340 void Eof() noexcept;
341
345
350
358 T Pop() noexcept;
359
367 T Front() const noexcept requires Type::CopyConstructible<T> && std::is_nothrow_copy_constructible_v<T>;
368
374 Hopper& operator>>(T& item) noexcept;
375
380 bool EoF() const noexcept;
381
386 bool Empty() const noexcept;
387
392 bool Ready() const noexcept;
393
397
402
415 void Notify(Safe::ConditionVariable& wake) noexcept;
416
426 void Notify(Safe::ConditionVariable& wake, Safe::Atomic<std::size_t>& generation) noexcept;
427
437 void Unnotify() noexcept;
438
442
452 friend Hopper& operator>>(T& item, Hopper& hopper) noexcept {
453 hopper << std::move(item);
454 return hopper;
455 }
456
463 friend Hopper& operator>>(T&& item, Hopper& hopper) noexcept {
464 hopper << std::move(item);
465 return hopper;
466 }
467
468 private:
472 friend class Sink<T>;
473
477 void AddWriter() noexcept;
478
482 void CloseWriter() noexcept;
483
487 void WakePending() noexcept;
488
499 QueueStatus Admit(T& item, StormByte::ByteSize bytes, const ByteBudget::Lease* lease,
500 std::chrono::milliseconds timeout, const Safe::Atomic<bool>* closed,
501 AdmissionWaitObserver observer = {}) noexcept;
502
509 void Notify(Safe::ConditionVariable& wake, const void* owner, Safe::Atomic<std::size_t>* generation) noexcept;
510
515 void Unnotify(const void* owner) noexcept;
516
521 class Implementation;
522
526 Implementation* m_io;
531 };
532 }
533}
534
536
541namespace StormByte {
546 namespace Type {
552 template<Buffer::Detail::HopperValue T>
553 struct IsMaybeSafe<Buffer::Hopper<T>>: std::true_type {};
554 }
555}
Shared charge that can explicitly follow one payload across queues or work.
Definition byte_budget.hxx:261
Shared logical byte accounting for queues and concurrent work.
Definition byte_budget.hxx:256
T Front() const noexcept
Copy of the next item without dequeuing.
void CancelPending() noexcept
Cancel admissions already waiting; future calls remain permitted.
StormByte::Size Capacity() const noexcept
Gets the current capacity ceiling.
QueueStatus PushFor(T &item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept
Admit with a bounded wait; zero attempts immediately.
bool Empty() const noexcept
Checks whether the queue has no pending items.
bool Ready() const noexcept
Whether Pop can return an item or production is finished.
void Eof() noexcept
Marks end of production and wakes waiters.
T Pop() noexcept
Pops one item from the bucket, or returns default-constructed T if dry.
Hopper() noexcept(false)
Constructs an empty unbounded Hopper.
QueueSnapshot Snapshot() const noexcept
Coherent counters under a short lock, without capacity waits or I/O.
unsigned Writers() const noexcept
Live writers attached to this hopper.
QueueStatus TryPush(T &item, StormByte::ByteSize bytes) noexcept
Attempt a weighted admission without waiting for capacity.
void Limits(QueueLimits limits) noexcept
Set independent local limits without discarding existing entries.
StormByte::Size Size() const noexcept
Gets the number of items currently waiting in the bucket.
QueueStatus PushFor(T &item, const ByteBudget::Lease &lease, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept
Admit with a shared charge and bounded wait.
QueueStatus Configure(QueueLimits limits, const ByteBudget &budget) noexcept
Attach aggregate accounting and local bounds to an empty hopper.
void Unnotify() noexcept
Drops both borrowed pointers set by Notify.
void Notify(Safe::ConditionVariable &wake) noexcept
Registers the consumer condition variable to notify on Push or Eof.
void Abort() noexcept
Close and discard entries, releasing charges outside the queue lock.
bool EoF() const noexcept
Checks whether Eof was called by a producer.
friend Hopper & operator>>(T &&item, Hopper &hopper) noexcept
Write: rvalue item flows into hopper.
Definition hopper.hxx:463
bool Full() const noexcept
Check whether an active local bound has been reached.
void Push(T item) noexcept
Enqueues one item and signals the consumer if Notify was configured.
Independent local bounds; absent means unlimited, engaged zero means zero capacity.
Definition byte_budget.hxx:125
Forward declaration of the keyed typed queue.
Definition sink.hxx:97
Values supported by the nonthrowing, Base-allocated typed queues.
Definition hopper.hxx:82
Private queue implementation contracts.
Buffer module of the StormByte suite.
QueueStatus
Admission outcomes.
Definition byte_budget.hxx:80
Detail::Owner Owner
Named concepts and small type utilities used across the suite.
Root namespace of the StormByte C++ suite.
STL namespace.
Borrowed, allocation-free observer for one synchronous PushFor call.
Definition byte_budget.hxx:117
HopperEntry() noexcept=default
Construct an empty entry before moving the caller's payload.
ByteBudget::Lease Charge
Shared aggregate charge.
Definition hopper.hxx:124
StormByte::ByteSize Bytes
Caller-defined logical weight.
Definition hopper.hxx:123
T Item
Caller payload.
Definition hopper.hxx:122
Coherent queue accounting; bytes are caller-supplied weights, never RSS.
Definition byte_budget.hxx:222