2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
4 * This file is part of StormByte-Buffer.
6 * StormByte-Buffer original source is dual-licensed:
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)
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>).
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
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.
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.
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>.
39 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
44#include <StormByte/safe/heap.hxx>
45#include <StormByte/safe/mutex.hxx>
46#include <StormByte/safe/queue.hxx>
47#include <StormByte/safe/unique_lock.hxx>
48#include <StormByte/type_traits.hxx>
59 * @namespace StormByte
60 * @brief Root namespace of the StormByte suite.
64 * @namespace StormByte::Type
65 * @brief Conditional Safe value declarations.
69 * @brief Certify provider-owned entries under the same payload/module contract as Hopper.
70 * @tparam T Supported nonthrowing Safe payload.
72 template<Buffer::Detail::HopperValue T>
73 struct IsMaybeSafe<Buffer::Detail::HopperEntry<T>>: std::true_type {};
78 * @namespace StormByte
79 * @brief Root namespace of the StormByte C++ suite.
83 * @namespace StormByte::Buffer
84 * @brief Buffer module of the StormByte suite.
88 * @class Hopper<T>::Implementation
89 * @brief Internal implementation of Hopper queue details.
91 * Handles mutex-protected queue operations, atomic capacity settings,
92 * condition variable notifications, and EoF flags. The gate, the signal
93 * and the words live on Base's heap.
95 template<Detail::HopperValue T>
96 class Hopper<T>::Implementation {
98 * @brief Provider-owned entry with logical weight and shared reservation.
100 using Entry = Detail::HopperEntry<T>;
104 * @brief Constructs an unbounded Implementation instance.
105 * @throws AllocationError The gate, the signal or a word cannot be allocated.
108 : m_eof(false), m_wake(nullptr), m_generation(nullptr), m_observer(nullptr), m_cap(std::size_t{0}), m_writers(1u) {}
111 * @brief Constructs a bounded Implementation instance.
112 * @param capacity Maximum items allowed.
113 * @throws AllocationError The gate, the signal or a word cannot be allocated.
115 explicit Implementation(StormByte::Size capacity)
116 : m_eof(false), m_wake(nullptr), m_generation(nullptr), m_observer(nullptr), m_cap(static_cast<std::size_t>(capacity)), m_writers(1u) {
117 if (capacity != StormByte::Size{0})
118 m_limits.Elements(capacity);
121 Implementation(const Implementation&) = delete;
123 Implementation(Implementation&&) = delete;
126 * @brief Destructor. Marks EoF and wakes waiting producers.
128 ~Implementation() noexcept {
129 m_eof.store(true, Safe::MemoryOrder::Release);
130 m_space.notify_all();
133 Implementation& operator=(const Implementation&) = delete;
135 Implementation& operator=(Implementation&&) = delete;
138 * @brief Gets capacity ceiling.
139 * @return Capacity value.
141 StormByte::Size Capacity() const noexcept {
142 return StormByte::Size{m_cap.load(Safe::MemoryOrder::Acquire)};
146 * @brief Sets capacity ceiling.
147 * @param capacity New capacity value.
149 void Capacity(StormByte::Size capacity) noexcept {
151 Safe::UniqueLock lock(m_mutex);
152 m_cap.store(static_cast<std::size_t>(capacity), Safe::MemoryOrder::Release);
153 if (capacity == StormByte::Size{0})
154 m_limits.UnlimitedElements();
156 m_limits.Elements(capacity);
158 m_space.notify_all();
163 * @brief Gets item count in queue.
164 * @return Count of items.
166 StormByte::Size Size() const noexcept {
167 Safe::UniqueLock lock(m_mutex);
168 return StormByte::Size{static_cast<std::size_t>(m_items.size())};
172 * @brief Check whether an active local bound has been reached.
173 * @return True at the item or byte ceiling, independently of aggregate pressure.
175 bool Full() const noexcept {
176 Safe::UniqueLock lock(m_mutex);
177 return (m_limits.ElementsLimited() && m_items.size() >= m_limits.Elements())
178 || (m_limits.BytesLimited() && m_bytes >= m_limits.Bytes());
182 * @brief Live writer count.
183 * @return Writers still open.
185 unsigned Writers() const noexcept {
186 return m_writers.load(Safe::MemoryOrder::Acquire);
190 * @brief Enqueues an item, waiting if full.
191 * @param item Item to enqueue.
193 void Push(T item) noexcept {
194 if constexpr (Type::NullablePointer<T>) {
199 Safe::UniqueLock lock(m_mutex);
201 m_space.wait(lock, [this]() -> bool {
202 const std::size_t cap = m_cap.load(Safe::MemoryOrder::Acquire);
203 return (cap == 0 && !m_limits.ElementsLimited())
204 || (m_limits.ElementsLimited() && m_items.size() < m_limits.Elements())
205 || m_eof.load(Safe::MemoryOrder::Acquire);
208 if (m_eof.load(Safe::MemoryOrder::Acquire))
211 auto entry = Safe::Shared<Entry>::template MakePointer<Entry>();
213 entry->Item = std::move(item);
225 * @brief Apply independent local bounds without dropping retained entries.
226 * @param limits New local ceilings.
228 void Limits(QueueLimits limits) noexcept {
230 Safe::UniqueLock lock(m_mutex);
232 m_cap.store(limits.ElementsLimited() ? static_cast<std::size_t>(limits.Elements()) : 0,
233 Safe::MemoryOrder::Release);
235 m_space.notify_all();
240 * @brief Change wake/accounting domains only when no admission or entry uses the old one.
241 * @param limits New local bounds.
242 * @param budget Shared accounting.
243 * @return Ok or Invalid without partial publication.
245 QueueStatus Configure(QueueLimits limits, const ByteBudget& budget) noexcept {
247 Safe::UniqueLock lock(m_mutex);
248 if (!m_items.empty() || m_active != 0)
249 return QueueStatus::Invalid;
252 m_cap.store(limits.ElementsLimited() ? static_cast<std::size_t>(limits.Elements()) : 0,
253 Safe::MemoryOrder::Release);
255 m_space.notify_all();
257 return QueueStatus::Ok;
261 * @brief Read queue counters without waiting for admissions.
262 * @return Coherent logical accounting.
264 QueueSnapshot Snapshot() const noexcept {
265 Safe::UniqueLock lock(m_mutex);
266 auto snapshot = m_snapshot;
267 snapshot.Limits = m_limits;
268 snapshot.Elements = StormByte::Size{m_items.size()};
269 snapshot.Bytes = m_bytes;
270 snapshot.Closed = m_eof.load(Safe::MemoryOrder::Acquire);
271 snapshot.Exists = true;
276 * @brief Wake shared-domain waiters after local state changes.
278 void WakePending() noexcept {
279 Safe::UniqueLock lock(m_mutex);
280 Detail::BudgetAccess::Notify(m_budget);
284 * @brief Cancel pending admissions in this hopper only.
286 void CancelPending() noexcept {
288 Safe::UniqueLock lock(m_mutex);
295 * @brief Close and move all entries out for destruction without the queue lock.
297 void Abort() noexcept {
298 Safe::Queue<Safe::Shared<Entry>> discarded;
300 Safe::UniqueLock lock(m_mutex);
301 m_eof.store(true, Safe::MemoryOrder::Release);
302 discarded.swap(m_items);
303 m_bytes = StormByte::ByteSize{0};
305 m_space.notify_all();
311 * @brief Reserve and insert with a bounded wait, never retaining partial admission charges.
312 * @param item Moved only after storage and charge succeed.
313 * @param bytes Logical entry weight.
314 * @param lease Optional shared charge.
315 * @param timeout Nonnegative bounded wait.
316 * @param closed Optional borrowed Sink closure flag.
317 * @param observer Borrowed wait observer, invoked without Buffer locks.
318 * @return Explicit admission result.
320 QueueStatus Admit(T& item, StormByte::ByteSize bytes, const ByteBudget::Lease* lease,
321 std::chrono::milliseconds timeout, const Safe::Atomic<bool>* closed,
322 AdmissionWaitObserver observer) noexcept {
323 if constexpr (Type::NullablePointer<T>) {
325 return QueueStatus::Empty;
327 const auto started = std::chrono::steady_clock::now();
328 if (timeout.count() < 0 || timeout > std::chrono::duration_cast<std::chrono::milliseconds>(
329 std::chrono::steady_clock::time_point::max() - started))
330 return QueueStatus::Invalid;
331 const auto deadline = started + timeout;
332 ByteBudget budget = [&] {
333 Safe::UniqueLock lock(m_mutex);
337 const auto initial = Detail::BudgetAccess::Event(budget);
338 std::size_t cancellation;
340 Safe::UniqueLock lock(m_mutex);
341 cancellation = m_cancellation;
344 QueueStatus result = QueueStatus::WouldBlock;
346 const auto event = Detail::BudgetAccess::Event(budget);
347 Safe::Shared<Entry> entry;
348 ByteBudget::Lease charge;
349 auto reason = AdmissionWaitReason::LocalCapacity;
351 Safe::UniqueLock lock(m_mutex);
352 const auto aggregate = budget.Snapshot();
353 if (m_eof.load(Safe::MemoryOrder::Acquire)
354 || (closed && closed->load(Safe::MemoryOrder::Acquire)))
355 result = QueueStatus::Closed;
356 else if (m_cancellation != cancellation || event.Cancellation != initial.Cancellation)
357 result = QueueStatus::Cancelled;
358 else if ((m_limits.ElementsLimited() && m_limits.Elements() == StormByte::Size{0})
359 || (m_limits.BytesLimited() && bytes > m_limits.Bytes()))
360 result = QueueStatus::TooLarge;
361 else if (lease && (!*lease || !lease->BelongsTo(budget) || lease->Bytes() != bytes))
362 result = QueueStatus::Invalid;
363 else if (aggregate.Closed)
364 result = QueueStatus::Closed;
365 else if (!lease && aggregate.Limited && bytes > aggregate.Limit)
366 result = QueueStatus::TooLarge;
367 else if ((m_limits.ElementsLimited() && m_items.size() >= m_limits.Elements())
368 || (m_limits.BytesLimited() && (m_bytes > m_limits.Bytes()
369 || bytes > m_limits.Bytes() - m_bytes)))
370 result = QueueStatus::WouldBlock;
371 else if (bytes > StormByte::ByteSize{std::numeric_limits<std::size_t>::max()} - m_bytes)
372 result = QueueStatus::TooLarge;
376 result = QueueStatus::Ok;
379 result = budget.TryReserve(bytes, charge);
380 if (result == QueueStatus::WouldBlock)
381 reason = AdmissionWaitReason::SharedBudget;
383 if (result == QueueStatus::Ok) {
385 entry = Safe::Shared<Entry>::template MakePointer<Entry>();
389 result = QueueStatus::Error;
391 if (result == QueueStatus::Ok) {
392 entry->Charge = std::move(charge);
393 entry->Bytes = bytes;
394 entry->Item = std::move(item);
395 m_bytes = m_bytes + bytes;
400 if (result == QueueStatus::WouldBlock)
401 ++m_snapshot.Pressure;
404 if (result != QueueStatus::WouldBlock || timeout.count() == 0)
406 if (std::chrono::steady_clock::now() >= deadline) {
407 result = QueueStatus::Timeout;
411 if (observer.Changed)
412 observer.Changed(observer.Context, reason, true);
413 Detail::BudgetAccess::Wait(budget, event, std::chrono::duration_cast<std::chrono::nanoseconds>(
414 deadline - std::chrono::steady_clock::now()).count());
415 if (observer.Changed)
416 observer.Changed(observer.Context, reason, false);
419 Safe::UniqueLock lock(m_mutex);
423 m_snapshot.WaitNanoseconds += std::chrono::duration_cast<std::chrono::nanoseconds>(
424 std::chrono::steady_clock::now() - started).count();
427 if (result == QueueStatus::Ok)
433 * @brief Signals end of production.
435 void Eof() noexcept {
437 Safe::UniqueLock lock(m_mutex);
438 m_eof.store(true, Safe::MemoryOrder::Release);
441 m_space.notify_all();
446 * @brief Registers an extra writer.
448 void AddWriter() noexcept {
449 m_writers.fetch_add(1u, Safe::MemoryOrder::AcqRel);
453 * @brief Releases one writer. Last writer force-closes.
455 void CloseWriter() noexcept {
456 unsigned prev = m_writers.load(Safe::MemoryOrder::Acquire);
458 if (m_writers.compare_exchange_weak(prev, static_cast<unsigned>(prev - 1),
459 Safe::MemoryOrder::AcqRel, Safe::MemoryOrder::Acquire)) {
468 * @brief Pops next item from queue without waiting.
469 * @return Next item, or default T if empty.
473 Safe::Shared<Entry> entry;
475 Safe::UniqueLock lock(m_mutex);
478 entry = std::move(m_items.front());
480 m_bytes = m_bytes - entry->Bytes;
482 item = std::move(entry->Item);
484 m_space.notify_all();
490 * @brief Copy of front item. Does not dequeue.
491 * @return Front or default T.
493 T Front() const noexcept requires Type::CopyConstructible<T> && std::is_nothrow_copy_constructible_v<T> {
494 Safe::UniqueLock lock(m_mutex);
497 return m_items.front()->Item;
501 * @brief Checks if Eof was signaled.
502 * @return true if Eof set.
504 bool EoF() const noexcept {
505 return m_eof.load(Safe::MemoryOrder::Acquire);
509 * @brief Checks if queue is empty.
510 * @return true if empty.
512 bool Empty() const noexcept {
513 Safe::UniqueLock lock(m_mutex);
514 return m_items.empty();
518 * @brief Item ready or production finished.
519 * @return true if !Empty() or EoF().
521 bool Ready() const noexcept {
522 return !Empty() || EoF();
526 * @brief Replaces the borrowed observer after any active notification finishes.
527 * @param wake Condition variable that remains alive until removal.
528 * @param owner Sink registration identity, or null for direct registration.
529 * @param generation Optional borrowed stored-event counter.
531 void Notify(Safe::ConditionVariable& wake, const void* owner = nullptr, Safe::Atomic<std::size_t>* generation = nullptr) noexcept {
532 Safe::UniqueLock lock(m_observer_mutex);
534 m_generation = generation;
539 * @brief Removes the observer and waits for any active notification.
541 void Unnotify() noexcept {
542 Safe::UniqueLock lock(m_observer_mutex);
544 m_generation = nullptr;
545 m_observer = nullptr;
549 * @brief Removes only the matching borrowed registration and waits for its notifications.
550 * @param owner Sink registration identity; never dereferenced.
552 void Unnotify(const void* owner) noexcept {
553 Safe::UniqueLock lock(m_observer_mutex);
554 if (m_observer == owner) {
556 m_generation = nullptr;
557 m_observer = nullptr;
563 * @brief Update peaks after insertion while the queue mutex is held.
565 void NotePeak() noexcept {
566 m_snapshot.PeakElements = std::max(m_snapshot.PeakElements, StormByte::Size{m_items.size()});
567 m_snapshot.PeakBytes = std::max(m_snapshot.PeakBytes, m_bytes);
570 QueueLimits m_limits; ///< Independent local limits.
571 ByteBudget m_budget; ///< Shared accounting and wake domain.
572 StormByte::ByteSize m_bytes {0}; ///< Live logical entry weights.
573 QueueSnapshot m_snapshot; ///< Lifetime peaks and pressure.
574 std::size_t m_active {0}; ///< Admissions retaining this wake domain.
575 std::size_t m_cancellation {0}; ///< Queue-local cancellation epoch.
578 * @brief Notifies registered consumer condition variable if set.
580 void SignalConsumer() noexcept {
581 Safe::UniqueLock lock(m_observer_mutex);
582 if (m_generation != nullptr) {
583 m_generation->fetch_add(std::size_t{1}, Safe::MemoryOrder::Release);
584 m_generation->notify_all();
586 if (m_wake != nullptr)
587 m_wake->notify_one();
591 * @brief Guards queue access.
593 mutable Safe::Mutex m_mutex;
595 * @brief Producer wait condition when full.
597 Safe::ConditionVariable m_space;
599 * @brief Item storage on Base's heap.
601 StormByte::Safe::Queue<Safe::Shared<Entry>> m_items;
603 * @brief End of production flag.
605 Safe::Atomic<bool> m_eof;
607 * @brief Serializes observer replacement, removal and use.
609 mutable Safe::Mutex m_observer_mutex;
611 * @brief Borrowed consumer condition variable, guarded by m_observer_mutex.
613 Safe::ConditionVariable* m_wake;
615 * @brief Borrowed event counter guarded by m_observer_mutex.
617 Safe::Atomic<std::size_t>* m_generation;
619 * @brief Sink registration identity guarded by m_observer_mutex; never dereferenced.
621 const void* m_observer;
623 * @brief Capacity ceiling (0 = unbounded).
625 Safe::Atomic<std::size_t> m_cap;
627 * @brief Live writers; last CloseWriter Eofs.
629 Safe::Atomic<unsigned> m_writers;
632 template<Detail::HopperValue T>
636 template<Detail::HopperValue T>
637 Hopper<T>::Hopper(StormByte::Size capacity)
638 : m_io(::new (StormByte::Safe::Heap::Allocate(sizeof(Implementation))) Implementation(capacity)),
639 m_owner(m_io, nullptr, [](void* context) noexcept {
640 static_cast<Implementation*>(context)->~Implementation();
641 StormByte::Safe::Heap::Free(context);
643 static_assert(alignof(Implementation) <= __STDCPP_DEFAULT_NEW_ALIGNMENT__);
646 template<Detail::HopperValue T>
647 Hopper<T>::~Hopper() noexcept = default;
649 template<Detail::HopperValue T>
650 StormByte::Size Hopper<T>::Capacity() const noexcept {
651 return m_io->Capacity();
654 template<Detail::HopperValue T>
655 void Hopper<T>::Capacity(StormByte::Size capacity) noexcept {
656 m_io->Capacity(capacity);
659 template<Detail::HopperValue T>
660 StormByte::Size Hopper<T>::Size() const noexcept {
664 template<Detail::HopperValue T>
665 bool Hopper<T>::Full() const noexcept {
669 template<Detail::HopperValue T>
670 unsigned Hopper<T>::Writers() const noexcept {
671 return m_io->Writers();
674 template<Detail::HopperValue T>
675 void Hopper<T>::Push(T item) noexcept {
676 m_io->Push(std::move(item));
679 template<Detail::HopperValue T>
680 QueueStatus Hopper<T>::TryPush(T& item, StormByte::ByteSize bytes) noexcept {
681 return Admit(item, bytes, nullptr, std::chrono::milliseconds{0}, nullptr);
684 template<Detail::HopperValue T>
685 QueueStatus Hopper<T>::TryPush(T& item, const ByteBudget::Lease& lease) noexcept {
686 return Admit(item, lease.Bytes(), &lease, std::chrono::milliseconds{0}, nullptr);
689 template<Detail::HopperValue T>
690 QueueStatus Hopper<T>::PushFor(T& item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout,
691 AdmissionWaitObserver observer) noexcept {
692 return Admit(item, bytes, nullptr, timeout, nullptr, observer);
695 template<Detail::HopperValue T>
696 QueueStatus Hopper<T>::PushFor(T& item, const ByteBudget::Lease& lease, std::chrono::milliseconds timeout,
697 AdmissionWaitObserver observer) noexcept {
698 return Admit(item, lease.Bytes(), &lease, timeout, nullptr, observer);
701 template<Detail::HopperValue T>
702 QueueStatus Hopper<T>::Admit(T& item, StormByte::ByteSize bytes, const ByteBudget::Lease* lease,
703 std::chrono::milliseconds timeout, const Safe::Atomic<bool>* closed, AdmissionWaitObserver observer) noexcept {
704 return m_io->Admit(item, bytes, lease, timeout, closed, observer);
707 template<Detail::HopperValue T>
708 void Hopper<T>::Limits(QueueLimits limits) noexcept {
709 m_io->Limits(limits);
712 template<Detail::HopperValue T>
713 QueueStatus Hopper<T>::Configure(QueueLimits limits, const ByteBudget& budget) noexcept {
714 return m_io->Configure(limits, budget);
717 template<Detail::HopperValue T>
718 QueueSnapshot Hopper<T>::Snapshot() const noexcept {
719 return m_io->Snapshot();
722 template<Detail::HopperValue T>
723 void Hopper<T>::WakePending() noexcept {
727 template<Detail::HopperValue T>
728 void Hopper<T>::CancelPending() noexcept {
729 m_io->CancelPending();
732 template<Detail::HopperValue T>
733 void Hopper<T>::Abort() noexcept {
737 template<Detail::HopperValue T>
738 Hopper<T>& Hopper<T>::operator<<(T item) noexcept {
739 Push(std::move(item));
743 template<Detail::HopperValue T>
744 void Hopper<T>::Eof() noexcept {
748 template<Detail::HopperValue T>
749 void Hopper<T>::AddWriter() noexcept {
753 template<Detail::HopperValue T>
754 void Hopper<T>::CloseWriter() noexcept {
758 template<Detail::HopperValue T>
759 T Hopper<T>::Pop() noexcept {
763 template<Detail::HopperValue T>
764 T Hopper<T>::Front() const noexcept requires Type::CopyConstructible<T> && std::is_nothrow_copy_constructible_v<T> {
765 return m_io->Front();
768 template<Detail::HopperValue T>
769 Hopper<T>& Hopper<T>::operator>>(T& item) noexcept {
774 template<Detail::HopperValue T>
775 bool Hopper<T>::EoF() const noexcept {
779 template<Detail::HopperValue T>
780 bool Hopper<T>::Empty() const noexcept {
781 return m_io->Empty();
784 template<Detail::HopperValue T>
785 bool Hopper<T>::Ready() const noexcept {
786 return m_io->Ready();
789 template<Detail::HopperValue T>
790 void Hopper<T>::Notify(Safe::ConditionVariable& wake) noexcept {
794 template<Detail::HopperValue T>
795 void Hopper<T>::Notify(Safe::ConditionVariable& wake, Safe::Atomic<std::size_t>& generation) noexcept {
796 m_io->Notify(wake, nullptr, &generation);
799 template<Detail::HopperValue T>
800 void Hopper<T>::Unnotify() noexcept {
804 template<Detail::HopperValue T>
805 void Hopper<T>::Notify(Safe::ConditionVariable& wake, const void* owner, Safe::Atomic<std::size_t>* generation) noexcept {
806 m_io->Notify(wake, owner, generation);
809 template<Detail::HopperValue T>
810 void Hopper<T>::Unnotify(const void* owner) noexcept {
811 m_io->Unnotify(owner);