StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
step.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-Multimedia.
5 *
6 * StormByte-Multimedia 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-Multimedia source in this
20 * file. Third-party components — including FFmpeg and embedded trained data —
21 * remain under their own licenses and are not covered by the commercial grant.
22 *
23 * A written StormByte commercial agreement may license this original source
24 * on terms other than the LGPL, including specific use, distribution or
25 * linking arrangements such as static linking, as stated in that agreement.
26 * It does not grant rights to dependencies or waive their license conditions.
27 * Enabling WITH_GPL or WITH_NONFREE may include components with separate
28 * obligations for modification, linking (static or dynamic), redistribution
29 * or works that incorporate them. The person modifying, linking, packaging or
30 * distributing the resulting work is responsible for determining and meeting
31 * all applicable requirements, including any needed patent permissions.
32 * A StormByte commercial agreement does not provide those rights for GPL or
33 * nonfree components.
34 *
35 * Neither license grants any patent rights. Any patent licenses required
36 * to use this software or third-party components must be obtained separately
37 * from the patent holders.
38 *
39 * StormByte-Multimedia is distributed in the hope that it will be useful,
40 * but WITHOUT ANY WARRANTY; without even the implied warranty of
41 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
42 * GNU Lesser General Public License for more details.
43 *
44 * You should have received a copy of the GNU Lesser General Public License
45 * version 3 along with StormByte-Multimedia. If not, see
46 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
47 *
48 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
49 */
50
51#pragma once
52
53#include <StormByte/size.hxx>
54#include <StormByte/buffer/sink.hxx>
55#include <StormByte/logger/log.hxx>
61#include <StormByte/safe/pointers.hxx>
62
63#include <cstddef>
64#include <cstdint>
65#include <limits>
66#include <optional>
67#include <string>
68#include <string_view>
69
79 class Host;
80
84 class Pipe;
85
89 class Pumper;
90
94 class Worker;
95
99 class TopologyAccess;
100}
101
107namespace StormByte {
113 namespace Multimedia {
119 namespace Pipeline {
123 class Decoder;
124
128 class Demuxer;
129
133 class Encoder;
134
138 class Muxer;
139
143 class Remuxer;
144
148 class Route;
149
153 class Filters;
154
158 class Step;
159
173
197 public:
202
207 Step(const Step& other) = delete;
208
213 Step(Step&& other) noexcept = delete;
214
218 virtual ~Step() noexcept;
219
225 Step& operator=(const Step& other) = delete;
226
232 Step& operator=(Step&& other) noexcept = delete;
233
237
242
246 void Wake() noexcept;
247
251
256
261 StormByte::Safe::Shared<class Plan> Plan() const noexcept;
262
266
271
276 inline const Kinds& Receives() const noexcept {
277 return m_receives;
278 }
279
284 inline const Kinds& Produces() const noexcept {
285 return m_produces;
286 }
287
292 State Status() const noexcept;
293
300 StormByte::Safe::Shared<const StageTelemetry> Telemetry() const;
301
310 StormByte::Buffer::QueueSnapshot QueueSnapshot(int track) const noexcept;
311
320 virtual bool Ready() const noexcept;
321
328 void Stop() noexcept;
329
336 virtual StormByte::Size InputCeiling() const noexcept;
337
341
346
351 bool Failed() const noexcept;
352
359 StormByte::Safe::Optional<StormByte::Safe::String> Error() const;
360
370 void Fail(StormByte::Safe::String reason) noexcept;
371
375 void Fail() noexcept;
376
381 STORMBYTE_FORCE_INLINE void Fail(const char* reason) noexcept {
382 Fail(std::string_view{reason ? reason : ""});
383 }
384
389 void Fail(std::string_view reason) noexcept;
390
394
395 protected:
401 bool Connect(Step& downstream) noexcept;
402
407 bool WaitPlan() noexcept;
408
413
424 enum Producer name,
425 Kinds receives, Kinds produces);
426
430
435
442 void Emit(Item::PointerType item) noexcept;
443
452 Item::PointerType CloneItem(const Item& item) const;
453
461 virtual void Wait() noexcept;
462
469 virtual bool WakeNow() const noexcept;
470
476 virtual void AfterWait() noexcept;
477
484 void Launch() noexcept;
485
492 void Halt() noexcept;
493
501 class Join final {
502 public:
507 explicit Join(Step& step) noexcept: m_step(step) {}
508
512 Join(const Join&) = delete;
513
517 Join(Join&&) noexcept = delete;
518
522 ~Join() noexcept {
523 m_step.Halt();
524 }
525
530 Join& operator=(const Join&) = delete;
531
536 Join& operator=(Join&&) noexcept = delete;
537
538 private:
539 Step& m_step;
540 };
541
546 bool Stopping() const noexcept;
547
552 void RecordWork(std::int64_t microseconds) noexcept;
553
558 std::int64_t LastWork() const noexcept;
559
563 void DumpWork() noexcept;
564
571 Backend::Pipeline::Host& Face() noexcept;
572
584 void Mount(StormByte::Safe::Unique<Backend::Pipeline::Pumper> pumper,
585 StormByte::Safe::Unique<Backend::Pipeline::Worker> worker);
586
590
595
601 virtual StormByte::Safe::String Label() const;
602
613 virtual void Log(StormByte::Logger::Level level, std::string_view message) noexcept;
614
618
623
624 private:
628 friend class Plan;
629
633 friend class Demuxer;
634
638 friend class Muxer;
639
643 friend class Remuxer;
644
648 friend class Route;
649
653 friend class Filters;
654
659
666 friend Decoder& operator>>(Demuxer& demuxer, Decoder& decoder) noexcept;
667
674
681 friend Demuxer& operator>>(StormByte::Safe::Shared<class Plan> plan, Demuxer& demuxer) noexcept;
682
689 friend Encoder& operator>>(Encoder& encoder, Muxer& muxer) noexcept;
690
697 friend Muxer& operator>>(Demuxer& demuxer, Muxer& muxer) noexcept;
698
705 friend Remuxer& operator>>(Demuxer& demuxer, Remuxer& remuxer) noexcept;
706
713 friend Remuxer& operator>>(Remuxer& remuxer, Muxer& muxer) noexcept;
714
721 friend Step& operator>>(Step& from, Step& to) noexcept;
722
726 class PrivateState;
727
728 PrivateState* m_state;
729
730 protected:
737 Backend::Pipeline::Pipe& pipe() noexcept;
738
745 const Backend::Pipeline::Pipe& pipe() const noexcept;
746
747 private:
751 class Surface;
752
756 void CloseHoppers() noexcept;
757
761 void WakeDownstream() noexcept;
762
767 void Plan(StormByte::Safe::Shared<class Plan> plan) noexcept;
768
773 void NotifyComplete(bool success) noexcept;
774
779 void Wire(Step& downstream) noexcept;
780
781 StormByte::Safe::Shared<class Plan> m_plan;
782 StormByte::Safe::Optional<StormByte::Safe::String> m_error;
783 StormByte::Safe::Shared<StageTelemetry> m_telemetry;
784 bool m_exhausted;
785 std::uint64_t m_workN;
786 std::int64_t m_workMin;
787 std::int64_t m_workMax;
788 std::int64_t m_lastWork;
789 };
790 }
791 }
792}
793
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Decodes packets of one origin track into frames.
Definition decoder.hxx:148
Reads interleaved compressed packets from the Plan reader.
Definition demuxer.hxx:148
Encodes frames of one output track into packets.
Definition encoder.hxx:145
Optional facade: Between stretches, Add filters, Close.
Definition filters.hxx:194
Facade shared by Frame and Packet.
Definition item.hxx:159
Bitmask of Kind.
Definition typedefs.hxx:179
Writes interleaved packets to the Plan writer.
Definition muxer.hxx:217
Forwards compressed packets of one origin track to the muxer.
Definition remuxer.hxx:133
Thread-safe counters and timings for one pipeline worker.
Definition telemetry.hxx:132
Join & operator=(const Join &)=delete
Copy assignment is disabled.
Join(const Join &)=delete
Copy construction is disabled.
Join(Step &step) noexcept
Guards the stage until execution finishes.
Definition step.hxx:507
Join & operator=(Join &&) noexcept=delete
Move assignment is disabled.
Join(Join &&) noexcept=delete
Move construction is disabled.
A pipeline stage that receives and emits media items.
Definition step.hxx:196
void DumpWork() noexcept
Writes min/max Process time at Debug.
bool Stopping() const noexcept
Worker must return (Stop, Halt or Fail).
virtual ~Step() noexcept
Destructor.
void Mount(StormByte::Safe::Unique< Backend::Pipeline::Pumper > pumper, StormByte::Safe::Unique< Backend::Pipeline::Worker > worker)
Step(const Step &other)=delete
Copy construction is disabled.
enum Producer m_name
UseLog leaf / default Label.
Definition step.hxx:620
friend class Backend::Pipeline::TopologyAccess
Allows topology telemetry to read the queue probe.
Definition step.hxx:658
void Wake() noexcept
Notifies all waiters of this step.
void Stop() noexcept
Requests shutdown and notifies connected stages.
bool WaitPlan() noexcept
Waits interruptibly for the shared plan to enter Running.
Item::PointerType CloneItem(const Item &item) const
Creates a distinct item through Item::Clone.
Backend::Pipeline::Host & Face() noexcept
virtual bool Ready() const noexcept
Whether this step can take work.
friend class Remuxer
Allows the remultiplexing stage to access step internals.
Definition step.hxx:643
StormByte::Safe::Shared< const StageTelemetry > Telemetry() const
Shared stage counters, retained independently of this Step.
void Fail(std::string_view reason) noexcept
Copies borrowed failure text before calling the DLL-safe overload.
const Kinds & Produces() const noexcept
Kinds this step emits.
Definition step.hxx:284
std::int64_t LastWork() const noexcept
Duration of the last timed Process, or 0.
virtual void AfterWait() noexcept
Work on the waiting worker after Wait unblocks.
Step(Step &&other) noexcept=delete
Move construction is disabled.
friend class Route
Allows route configuration to access step internals.
Definition step.hxx:648
Kinds m_receives
Receives.
Definition step.hxx:621
void Fail(StormByte::Safe::String reason) noexcept
Marks the stage as failed and notifies connected stages.
bool Failed() const noexcept
Whether this step has failed.
const Kinds & Receives() const noexcept
Kinds this step consumes.
Definition step.hxx:276
virtual StormByte::Size InputCeiling() const noexcept
Maximum number of queued input items.
virtual bool WakeNow() const noexcept
Extra reason to leave Wait.
virtual StormByte::Safe::String Label() const
Display name of this step.
void Halt() noexcept
Stops the stage and waits for execution to finish.
StormByte::Safe::Shared< StormByte::Logger::Log > m_log
Scoped logger retained through Base-heap shared ownership.
Definition step.hxx:619
friend class Filters
Allows filter configuration to access step internals.
Definition step.hxx:653
friend class Demuxer
Allows the demultiplexing stage to access step internals.
Definition step.hxx:633
void Launch() noexcept
Starts stage initialization and processing.
State Status() const noexcept
Current lifecycle value.
bool Connect(Step &downstream) noexcept
Registers a borrowed downstream stage and shares any bound plan.
virtual void Wait() noexcept
Waits until input is available, the stage fails or stops, or WakeNow.
void RecordWork(std::int64_t microseconds) noexcept
Adds one Process duration to the step summary.
StormByte::Buffer::QueueSnapshot QueueSnapshot(int track) const noexcept
Reads effective queue limits and logical-byte accounting.
friend class Muxer
Allows the multiplexing stage to access step internals.
Definition step.hxx:638
Backend::Pipeline::Pipe & pipe() noexcept
Kinds m_produces
Produces.
Definition step.hxx:622
friend class Plan
Allows the shared plan to wake registered stages.
Definition step.hxx:628
void Emit(Item::PointerType item) noexcept
Sends item to connected consumers.
virtual void Log(StormByte::Logger::Level level, std::string_view message) noexcept
Writes one log line on the scoped module logger.
StormByte::Safe::Optional< StormByte::Safe::String > Error() const
Failure text.
State
Lifecycle of the stage thread.
Definition typedefs.hxx:211
Producer
Named stage of the tube.
Definition typedefs.hxx:136
@ Route
A configured connection between pipeline stages.
Definition typedefs.hxx:141
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Typed item queues provided by StormByte-Buffer.
Multimedia-owned pipeline stages and unit holders.
Demux / decode / filter / encode / mux types.
Decoder & operator>>(Demuxer &demuxer, Decoder &decoder) noexcept
Binds one origin track of demuxer to decoder.
@ Pipe
Buffer::Sink hopper owned by its consumer stage.
Definition telemetry.hxx:429
Multimedia module of the StormByte suite.
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_FORCE_INLINE
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61