StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
sink.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
44#include <StormByte/type_traits/safe.hxx>
45
47#include <StormByte/safe/atomic.hxx>
48#include <StormByte/safe/condition_variable.hxx>
49#include <StormByte/safe/function.hxx>
50#include <StormByte/safe/pointers.hxx>
51#include <StormByte/safe/vector.hxx>
52#include <StormByte/size.hxx>
53#include <StormByte/type_traits.hxx>
54
55#include <cstddef>
56#include <functional>
57
62namespace StormByte {
67 namespace Buffer {
96 template<Detail::HopperValue T>
97 class Sink {
98 public:
111
116
122
123 Sink(const Sink&) = delete;
124
125 Sink(Sink&&) noexcept = delete;
126
130 ~Sink() noexcept;
131
132 Sink& operator=(const Sink&) = delete;
133
134 Sink& operator=(Sink&&) noexcept = delete;
135
139
144
155 void Push(int key, T item) noexcept;
156
164 QueueStatus TryPush(int key, T& item, StormByte::ByteSize bytes) noexcept;
165
173 QueueStatus TryPush(int key, T& item, const ByteBudget::Lease& lease) noexcept;
174
184 QueueStatus PushFor(int key, T& item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout,
185 AdmissionWaitObserver observer = {}) noexcept;
186
196 QueueStatus PushFor(int key, T& item, const ByteBudget::Lease& lease,
197 std::chrono::milliseconds timeout, AdmissionWaitObserver observer = {}) noexcept;
198
205 QueueStatus Limits(int key, QueueLimits limits) noexcept;
206
214 QueueStatus Configure(int key, QueueLimits limits, const ByteBudget& budget) noexcept;
215
221 QueueSnapshot Snapshot(int key) const noexcept;
222
227 void CancelPending(int key) noexcept;
228
238 void Eof() noexcept;
239
247 void Abort() noexcept;
248
252
257
262 class Lane {
263 public:
273 Sink& operator>>(Sink& dest) noexcept;
274
275 private:
279 friend class Sink;
285 Lane(Sink& from, int key) noexcept;
286
290 Sink* m_from;
294 int m_key;
295 };
296
302 Lane To(int key) noexcept;
303
311 Sink& operator>>(Sink& dest) noexcept;
312
318 Sink& operator<<(Sink& src) noexcept;
319
325 Sink& operator<<(Lane lane) noexcept;
326
330 void Drain() noexcept;
331
336 bool Draining() const noexcept;
337
346 void Notify(Safe::ConditionVariable& consumer) noexcept;
347
358 void Notify(Safe::ConditionVariable& consumer, Safe::Atomic<std::size_t>& generation) noexcept;
359
368 void Unnotify() noexcept;
369
373
378
385 StormByte::Safe::Vector<int> Keys() const noexcept;
386
391 StormByte::Size Buckets() const noexcept;
392
398 bool Contains(int key) const noexcept;
399
405 StormByte::Size Capacity(int key) const noexcept;
406
412 void Capacity(int key, StormByte::Size capacity) noexcept;
413
419 StormByte::Size Size(int key) const noexcept;
420
426 bool Full(int key) const noexcept;
427
433 bool Empty(int key) const noexcept;
434
440 bool EoF(int key) const noexcept;
441
447 bool Ready(int key) const noexcept;
448
458 T Front(int key) const noexcept requires Type::CopyConstructible<T> && std::is_nothrow_copy_constructible_v<T>;
459
463
468
475 T Pop() noexcept;
476
487 T Pop(const Select& select) noexcept;
488
500 template<typename Selector>
501 requires (!Type::SameAs<std::remove_cvref_t<Selector>, Select>) &&
502 requires(Selector& select, StormByte::Size count) {
503 { std::invoke(select, count) } -> Type::SameAs<StormByte::Size>;
504 }
505 T Pop(Selector&& select) noexcept;
506
518 T Pop(int key) noexcept;
519
533 bool EoF() const noexcept;
534
539 bool Ready() const noexcept;
540
544
545 private:
550 class Implementation;
551
555 Implementation* m_io;
559 StormByte::Safe::Owner m_owner;
560 };
561 }
562}
563
564#include <StormByte/buffer/sink.txx>
565
570namespace StormByte {
575 namespace Type {
581 template<Buffer::Detail::HopperValue T>
582 struct IsMaybeSafe<Buffer::Sink<T>>: std::true_type {};
583 }
584}
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
Independent local bounds; absent means unlimited, engaged zero means zero capacity.
Definition byte_budget.hxx:125
One-key redirect: from.To(key) >> dest.
Definition sink.hxx:262
friend class Sink
Grants the enclosing Sink access to the borrowed lane.
Definition sink.hxx:279
Sink & operator>>(Sink &dest) noexcept
Wire this key onto dest.
bool EoF(int key) const noexcept
Whether producers marked Eof on bucket key.
QueueSnapshot Snapshot(int key) const noexcept
Read shared-hopper counters without waiting for capacity or doing I/O.
void Notify(Safe::ConditionVariable &consumer) noexcept
Registers consumer condition variable to notify on all current and future hoppers.
Sink & operator>>(Sink &dest) noexcept
Share every existing hopper with dest.
StormByte::Size Buckets() const noexcept
Number of hoppers wired on this Sink.
Lane To(int key) noexcept
Redirect of one hopper key.
bool Contains(int key) const noexcept
Whether hopper key exists on this Sink.
void Unnotify() noexcept
Removes only this Sink's matching borrowed registrations.
void Drain() noexcept
Marks Sink as a terminal producer (un-wired Push calls drop instead of waiting).
StormByte::Size Size(int key) const noexcept
Gets pending item count in bucket key.
QueueStatus PushFor(int key, T &item, const ByteBudget::Lease &lease, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept
Shared-charge admission with a bounded wait.
StormByte::Size Capacity(int key) const noexcept
Gets capacity ceiling of bucket key.
Sink(const Sink &)=delete
T Front(int key) const noexcept
Copy of the next item in bucket key without dequeuing.
StormByte::Safe::Vector< int > Keys() const noexcept
Keys of hoppers currently wired on this Sink.
bool Full(int key) const noexcept
Checks if bucket key is full.
bool Draining() const noexcept
Checks whether Drain was called.
QueueStatus Configure(int key, QueueLimits limits, const ByteBudget &budget) noexcept
Attach local limits and aggregate accounting to an empty, idle bucket.
void Push(int key, T item) noexcept
Pushes an item into the bucket specified by key.
QueueStatus Limits(int key, QueueLimits limits) noexcept
Configure independent local limits on an existing shared hopper.
bool Empty(int key) const noexcept
Whether bucket key has no pending items.
Sink(Sink &&) noexcept=delete
Sink & operator<<(Sink &src) noexcept
Same as src >> *this (all hoppers).
void CancelPending(int key) noexcept
Cancel weighted admissions currently waiting on a shared hopper.
T Pop(int key) noexcept
Pops one item from bucket key only.
StormByte::Safe::Function< StormByte::Size(StormByte::Size)> Select
Index chooser for Pop selection across multiple buckets.
Definition sink.hxx:110
bool EoF() const noexcept
Checks if the Sink is finished.
QueueStatus PushFor(int key, T &item, StormByte::ByteSize bytes, std::chrono::milliseconds timeout, AdmissionWaitObserver observer={}) noexcept
Weighted admission with a bounded wait, cancellable by this Sink's closure.
bool Ready(int key) const noexcept
Whether Pop(int) on key can return an item or that hopper is finished.
T Pop(Selector &&select) noexcept
Pops using a synchronously borrowed callable without copying its captures.
Sink()
Constructs an empty Sink with zero buckets.
Sink & operator<<(Lane lane) noexcept
Same as lane >> *this.
void Eof() noexcept
Closes the Sink and releases writer holds on its hoppers.
QueueStatus TryPush(int key, T &item, StormByte::ByteSize bytes) noexcept
Attempt a weighted admission to an existing bucket.
T Pop() noexcept
Pops one item from the Sink using default round-robin order.
void Abort() noexcept
Closes every connected hopper and discards queued items.
Buffer module of the StormByte suite.
QueueStatus
Admission outcomes.
Definition byte_budget.hxx:80
Root namespace of the StormByte C++ suite.
STL namespace.
Borrowed, allocation-free observer for one synchronous PushFor call.
Definition byte_budget.hxx:117
Coherent queue accounting; bytes are caller-supplied weights, never RSS.
Definition byte_budget.hxx:222