StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Multimedia::Pipeline::Step Class Reference

A pipeline stage that receives and emits media items. More...

#include <StormByte/multimedia/pipeline/step.hxx>

Inheritance diagram for StormByte::Multimedia::Pipeline::Step:
Collaboration diagram for StormByte::Multimedia::Pipeline::Step:

Classes

class  Join
 Ensures a derived stage stops before its resources expire. More...

Public Member Functions

Lifecycle
 Step (const Step &other)=delete
 Copy construction is disabled.
 Step (Step &&other) noexcept=delete
 Move construction is disabled.
virtual ~Step () noexcept
 Destructor.
Step & operator= (const Step &other)=delete
 Copy assignment is disabled.
Step & operator= (Step &&other) noexcept=delete
 Move assignment is disabled.
Sinks
void Wake () noexcept
 Notifies all waiters of this step.
Plan
StormByte::Safe::Shared< class Plan > Plan () const noexcept
 Bound job intention, if any.
Flow
const Kinds & Receives () const noexcept
 Kinds this step consumes.
const Kinds & Produces () const noexcept
 Kinds this step emits.
State Status () const noexcept
 Current lifecycle value.
StormByte::Safe::Shared< const StageTelemetry > Telemetry () const
 Shared stage counters, retained independently of this Step.
StormByte::Buffer::QueueSnapshot QueueSnapshot (int track) const noexcept
 Reads effective queue limits and logical-byte accounting.
virtual bool Ready () const noexcept
 Whether this step can take work.
void Stop () noexcept
 Requests shutdown and notifies connected stages.
virtual StormByte::Size InputCeiling () const noexcept
 Maximum number of queued input items.
Failure
bool Failed () const noexcept
 Whether this step has failed.
StormByte::Safe::Optional< StormByte::Safe::String > Error () const
 Failure text.
void Fail (StormByte::Safe::String reason) noexcept
 Marks the stage as failed and notifies connected stages.
void Fail () noexcept
 Marks failure without storing a message or allocating.
STORMBYTE_FORCE_INLINE void Fail (const char *reason) noexcept
 Copies a null-terminated failure literal into Safe storage.
void Fail (std::string_view reason) noexcept
 Copies borrowed failure text before calling the DLL-safe overload.

Protected Member Functions

bool Connect (Step &downstream) noexcept
 Registers a borrowed downstream stage and shares any bound plan.
bool WaitPlan () noexcept
 Waits interruptibly for the shared plan to enter Running.
Backend::Pipeline::Pipe & pipe () noexcept
const Backend::Pipeline::Pipe & pipe () const noexcept
Construction
 Step (StormByte::Safe::Shared< StormByte::Logger::Log > log, enum Producer name, Kinds receives, Kinds produces)
 Constructs a stage in State::Created.
Work
void Emit (Item::PointerType item) noexcept
 Sends item to connected consumers.
Item::PointerType CloneItem (const Item &item) const
 Creates a distinct item through Item::Clone.
virtual void Wait () noexcept
 Waits until input is available, the stage fails or stops, or WakeNow.
virtual bool WakeNow () const noexcept
 Extra reason to leave Wait.
virtual void AfterWait () noexcept
 Work on the waiting worker after Wait unblocks.
void Launch () noexcept
 Starts stage initialization and processing.
void Halt () noexcept
 Stops the stage and waits for execution to finish.
bool Stopping () const noexcept
 Worker must return (Stop, Halt or Fail).
void RecordWork (std::int64_t microseconds) noexcept
 Adds one Process duration to the step summary.
std::int64_t LastWork () const noexcept
 Duration of the last timed Process, or 0.
void DumpWork () noexcept
 Writes min/max Process time at Debug.
Backend::Pipeline::Host & Face () noexcept
void Mount (StormByte::Safe::Unique< Backend::Pipeline::Pumper > pumper, StormByte::Safe::Unique< Backend::Pipeline::Worker > worker)
Logging
virtual StormByte::Safe::String Label () const
 Display name of this step.
virtual void Log (StormByte::Logger::Level level, std::string_view message) noexcept
 Writes one log line on the scoped module logger.

Protected Attributes

StormByte::Safe::Shared< StormByte::Logger::Log > m_log
 Scoped logger retained through Base-heap shared ownership.
enum Producer m_name
 UseLog leaf / default Label.
Kinds m_receives
 Receives.
Kinds m_produces
 Produces.

Friends

class Plan
 Allows the shared plan to wake registered stages.
class Demuxer
 Allows the demultiplexing stage to access step internals.
class Muxer
 Allows the multiplexing stage to access step internals.
class Remuxer
 Allows the remultiplexing stage to access step internals.
class Route
 Allows route configuration to access step internals.
class Filters
 Allows filter configuration to access step internals.
class Backend::Pipeline::TopologyAccess
 Allows topology telemetry to read the queue probe.
Decoder & operator>> (Demuxer &demuxer, Decoder &decoder)
 Connects a demultiplexing stage to a decoding stage.
Demuxer & operator>> (StormByte::Safe::Shared< class Plan > plan, Demuxer &demuxer)
 Binds a plan to a demultiplexing stage.
Encoder & operator>> (Encoder &encoder, Muxer &muxer)
 Connects an encoding stage to a multiplexing stage.
Muxer & operator>> (Demuxer &demuxer, Muxer &muxer)
 Connects a demultiplexing stage to a multiplexing stage.
Remuxer & operator>> (Demuxer &demuxer, Remuxer &remuxer)
 Connects a demultiplexing stage to a remultiplexing stage.
Remuxer & operator>> (Remuxer &remuxer, Muxer &muxer)
 Connects a remultiplexing stage to a multiplexing stage.
Step & operator>> (Step &from, Step &to)
 Connects output from one step to another.

Detailed Description

A pipeline stage that receives and emits media items.

Connect stages with operator>> and inspect their lifecycle with Status. The accepted and produced item kinds describe which connections are compatible.

Log scopes use the StormByte/Multimedia/ prefix followed by the producer name. The supplied logger controls throttling.

Filters can attach analytics without changing the items delivered to the next processing stage.

DLL boundary
Backend storage and synchronization are created and released by Multimedia. Retained owners use Safe storage. Compatible C++ ABI and loaded Base, Multimedia and derived-class providers are required through destruction. Derived classes must preserve these ownership and lifetime guarantees.

Constructor & Destructor Documentation

◆ Step() [1/3]

StormByte::Multimedia::Pipeline::Step::Step ( const Step & other)
delete

Copy construction is disabled.

Parameters
otherSource stage.

◆ Step() [2/3]

StormByte::Multimedia::Pipeline::Step::Step ( Step && other)
deletenoexcept

Move construction is disabled.

Parameters
otherSource stage.

◆ ~Step()

virtual StormByte::Multimedia::Pipeline::Step::~Step ( )
virtualnoexcept

Destructor.

Waits for stage execution to finish.

◆ Step() [3/3]

StormByte::Multimedia::Pipeline::Step::Step ( StormByte::Safe::Shared< StormByte::Logger::Log > log,
enum Producer name,
Kinds receives,
Kinds produces )
protected

Constructs a stage in State::Created.

Parameters
logBase-heap shared logger. Prefer StormByte::Logger::ThreadedLog when several workers write. A plain Log is accepted for single-thread use. Empty pointer means no log.
nameStage name for log scope and default Label.
receivesKinds this step consumes.
producesKinds this step emits.

Member Function Documentation

◆ AfterWait()

virtual void StormByte::Multimedia::Pipeline::Step::AfterWait ( )
protectedvirtualnoexcept

Work on the waiting worker after Wait unblocks.

Default no-op. Leaf office.

◆ CloneItem()

Item::PointerType StormByte::Multimedia::Pipeline::Step::CloneItem ( const Item & item) const
protected

Creates a distinct item through Item::Clone.

Parameters
itemUnit to clone.
Returns
Owning pointer, or empty if item cannot clone.

Media buffers are shared according to Item::Clone; the returned item does not duplicate the media payload.

◆ Connect()

bool StormByte::Multimedia::Pipeline::Step::Connect ( Step & downstream)
protectednoexcept

Registers a borrowed downstream stage and shares any bound plan.

Parameters
downstreamStage retained by the graph owner until assembly and execution end.
Returns
true when both stages share a compatible plan.

◆ DumpWork()

void StormByte::Multimedia::Pipeline::Step::DumpWork ( )
protectednoexcept

Writes min/max Process time at Debug.

No-op if none.

◆ Emit()

void StormByte::Multimedia::Pipeline::Step::Emit ( Item::PointerType item)
protectednoexcept

Sends item to connected consumers.

Parameters
itemUnit to emit. Empty is a no-op.

Configured analytics receive copies without changing item.

◆ Error()

StormByte::Safe::Optional< StormByte::Safe::String > StormByte::Multimedia::Pipeline::Step::Error ( ) const

Failure text.

Returns
Message, or empty.
Note
A failed stage may have no text after an allocation failure. Use Failed() to determine the authoritative state.

◆ Face()

Backend::Pipeline::Host & StormByte::Multimedia::Pipeline::Step::Face ( )
protectednoexcept

◆ Fail() [1/4]

void StormByte::Multimedia::Pipeline::Step::Fail ( )
noexcept

Marks failure without storing a message or allocating.

◆ Fail() [2/4]

STORMBYTE_FORCE_INLINE void StormByte::Multimedia::Pipeline::Step::Fail ( const char * reason)
inlinenoexcept

Copies a null-terminated failure literal into Safe storage.

Parameters
reasonMessage literal; null becomes an empty message.

◆ Fail() [3/4]

void StormByte::Multimedia::Pipeline::Step::Fail ( std::string_view reason)
noexcept

Copies borrowed failure text before calling the DLL-safe overload.

Parameters
reasonBorrowed message, used only during this call.

◆ Fail() [4/4]

void StormByte::Multimedia::Pipeline::Step::Fail ( StormByte::Safe::String reason)
noexcept

Marks the stage as failed and notifies connected stages.

Returns without waiting for completion. Stores the reason in Error and logs it when memory is available. Allocation failures fall back to Fail() without a message.

Parameters
reasonMessage.

◆ Failed()

bool StormByte::Multimedia::Pipeline::Step::Failed ( ) const
noexcept

Whether this step has failed.

Returns
true iff Status is Failed.

◆ Halt()

void StormByte::Multimedia::Pipeline::Step::Halt ( )
protectednoexcept

Stops the stage and waits for execution to finish.

Safe to call more than once. Returns after stage execution finishes. Filter plugins do not need to call this.

◆ InputCeiling()

virtual StormByte::Size StormByte::Multimedia::Pipeline::Step::InputCeiling ( ) const
virtualnoexcept

Maximum number of queued input items.

Returns
Max queued items. 0 means unbounded.

Derived stages override this to specify their input limit.

Reimplemented in StormByte::Multimedia::Pipeline::Decoder, StormByte::Multimedia::Pipeline::Encoder, StormByte::Multimedia::Pipeline::Muxer, and StormByte::Multimedia::Pipeline::Remuxer.

◆ Label()

virtual StormByte::Safe::String StormByte::Multimedia::Pipeline::Step::Label ( ) const
protectedvirtual

Display name of this step.

Returns
Producer name (Encoder) unless a leaf overrides it (Encoder(libx265)).

◆ LastWork()

std::int64_t StormByte::Multimedia::Pipeline::Step::LastWork ( ) const
protectednoexcept

Duration of the last timed Process, or 0.

Returns
Microseconds.

◆ Launch()

void StormByte::Multimedia::Pipeline::Step::Launch ( )
protectednoexcept

Starts stage initialization and processing.

Idempotent. No-op without an execution handler, or if the stage has already Failed or Stopped.

◆ Log()

virtual void StormByte::Multimedia::Pipeline::Step::Log ( StormByte::Logger::Level level,
std::string_view message )
protectedvirtualnoexcept

Writes one log line on the scoped module logger.

Parameters
levelStormByte::Logger::Level of this line.
messageAlready-formatted text (caller may use Safe::String::ReplaceToken). Must not include the level name; Logger prints that.

No-op without a logger. Overrides may customize delivery. The component scope uses the StormByte/Multimedia/ prefix followed by the stage name.

◆ Mount()

void StormByte::Multimedia::Pipeline::Step::Mount ( StormByte::Safe::Unique< Backend::Pipeline::Pumper > pumper,
StormByte::Safe::Unique< Backend::Pipeline::Worker > worker )
protected

◆ operator=() [1/2]

Step & StormByte::Multimedia::Pipeline::Step::operator= ( const Step & other)
delete

Copy assignment is disabled.

Parameters
otherSource stage.
Returns
This stage.

◆ operator=() [2/2]

Step & StormByte::Multimedia::Pipeline::Step::operator= ( Step && other)
deletenoexcept

Move assignment is disabled.

Parameters
otherSource stage.
Returns
This stage.

◆ pipe() [1/2]

const Backend::Pipeline::Pipe & StormByte::Multimedia::Pipeline::Step::pipe ( ) const
protectednoexcept

◆ pipe() [2/2]

Backend::Pipeline::Pipe & StormByte::Multimedia::Pipeline::Step::pipe ( )
protectednoexcept

◆ Plan()

StormByte::Safe::Shared< class Plan > StormByte::Multimedia::Pipeline::Step::Plan ( ) const
noexcept

Bound job intention, if any.

Returns
Shared Plan, or empty.

◆ Produces()

const Kinds & StormByte::Multimedia::Pipeline::Step::Produces ( ) const
inlinenoexcept

Kinds this step emits.

Returns
Mask set at construction.

◆ QueueSnapshot()

StormByte::Buffer::QueueSnapshot StormByte::Multimedia::Pipeline::Step::QueueSnapshot ( int track) const
noexcept

Reads effective queue limits and logical-byte accounting.

Parameters
trackInput track key.
Returns
Coherent snapshot; Exists is false before the queue is wired.

Read the requested policy from Plan::Buffering. Snapshot byte weights are logical estimates, not physical memory or RSS.

◆ Ready()

virtual bool StormByte::Multimedia::Pipeline::Step::Ready ( ) const
virtualnoexcept

Whether this step can take work.

By default, Status must be State::Ready. Muxer also requires Muxer::Armed before writing output.

Returns
true when the stage is open for work.

Reimplemented in StormByte::Multimedia::Pipeline::Muxer.

◆ Receives()

const Kinds & StormByte::Multimedia::Pipeline::Step::Receives ( ) const
inlinenoexcept

Kinds this step consumes.

Returns
Mask set at construction.

◆ RecordWork()

void StormByte::Multimedia::Pipeline::Step::RecordWork ( std::int64_t microseconds)
protectednoexcept

Adds one Process duration to the step summary.

Parameters
microsecondsWall time of that Process call.

◆ Status()

State StormByte::Multimedia::Pipeline::Step::Status ( ) const
noexcept

Current lifecycle value.

Returns
State of this step only.

◆ Stop()

void StormByte::Multimedia::Pipeline::Step::Stop ( )
noexcept

Requests shutdown and notifies connected stages.

Returns without waiting for completion. Safe to call more than once. A stopped stage cannot be restarted.

◆ Stopping()

bool StormByte::Multimedia::Pipeline::Step::Stopping ( ) const
protectednoexcept

Worker must return (Stop, Halt or Fail).

Returns
true if Status is Stopping, Stopped or Failed.

◆ Telemetry()

StormByte::Safe::Shared< const StageTelemetry > StormByte::Multimedia::Pipeline::Step::Telemetry ( ) const

Shared stage counters, retained independently of this Step.

Refreshing the owned stage label may allocate.

Returns
Const metrics handle identifying this stage.

◆ Wait()

virtual void StormByte::Multimedia::Pipeline::Step::Wait ( )
protectedvirtualnoexcept

Waits until input is available, the stage fails or stops, or WakeNow.

After the CV unblocks, runs AfterWait on this worker. Step does not interpret WakeNow.

◆ WaitPlan()

bool StormByte::Multimedia::Pipeline::Step::WaitPlan ( )
protectednoexcept

Waits interruptibly for the shared plan to enter Running.

Returns
false when the stage or shared plan stops or fails.

◆ Wake()

void StormByte::Multimedia::Pipeline::Step::Wake ( )
noexcept

Notifies all waiters of this step.

◆ WakeNow()

virtual bool StormByte::Multimedia::Pipeline::Step::WakeNow ( ) const
protectedvirtualnoexcept

Extra reason to leave Wait.

Returns
true to wake without available input. Default false.

Leaf office. Step does not know why the leaf wakes.

◆ Backend::Pipeline::TopologyAccess

friend class Backend::Pipeline::TopologyAccess
friend

Allows topology telemetry to read the queue probe.

◆ Demuxer

friend class Demuxer
friend

Allows the demultiplexing stage to access step internals.

◆ Filters

friend class Filters
friend

Allows filter configuration to access step internals.

◆ Muxer

friend class Muxer
friend

Allows the multiplexing stage to access step internals.

◆ operator>> [1/7]

Decoder & operator>> ( Demuxer & demuxer,
Decoder & decoder )
friend

Connects a demultiplexing stage to a decoding stage.

Parameters
demuxerProducer stage.
decoderConsumer stage.
Returns
The decoding stage.
Parameters
demuxerOrigin demuxer.
decoderDestination decoder.
Returns
decoder.

◆ operator>> [2/7]

Muxer & operator>> ( Demuxer & demuxer,
Muxer & muxer )
friend

Connects a demultiplexing stage to a multiplexing stage.

Parameters
demuxerProducer stage.
muxerConsumer stage.
Returns
The multiplexing stage.

Allows demuxer connections to bind the remux origin.

Required when any remux track is reserved. Without it the muxer cannot clone origin codec parameters. Also shares the tube Progress clock. Does not open the writer during connection. There is no file >> muxer and no muxer >> path.

Parameters
demuxerOrigin demuxer. Must outlive header write.
muxerDestination.
Returns
muxer.

◆ operator>> [3/7]

Remuxer & operator>> ( Demuxer & demuxer,
Remuxer & remuxer )
friend

Connects a demultiplexing stage to a remultiplexing stage.

Parameters
demuxerProducer stage.
remuxerConsumer stage.
Returns
The remultiplexing stage.

Connect the origin demuxer to this remuxer.

Parameters
demuxerOrigin demuxer.
remuxerDestination remuxer.
Returns
remuxer.

◆ operator>> [4/7]

Encoder & operator>> ( Encoder & encoder,
Muxer & muxer )
friend

Connects an encoding stage to a multiplexing stage.

Parameters
encoderProducer stage.
muxerConsumer stage.
Returns
The encoding stage.

Allows encoder connections to reserve output tracks.

Parameters
encoderLive encoder.
muxerDestination.
Returns
encoder.
Registers a borrowed graph edge and binds the typed packet lane,
even without a Plan. Backend reservation and writer opening are
deferred until Setup observes a running Plan.

◆ operator>> [5/7]

Remuxer & operator>> ( Remuxer & remuxer,
Muxer & muxer )
friend

Connects a remultiplexing stage to a multiplexing stage.

Parameters
remuxerProducer stage.
muxerConsumer stage.
Returns
The remultiplexing stage.

Connect this remuxer to the destination muxer.

Allows remuxer connections to reserve output tracks.

Parameters
remuxerLive remuxer.
muxerDestination.
Returns
remuxer.
Registers a borrowed graph edge and binds the typed packet lane,
even without a Plan. Backend reservation and writer opening are
deferred until Setup observes a running Plan.

◆ operator>> [6/7]

Step & operator>> ( Step & from,
Step & to )
friend

Connects output from one step to another.

Parameters
fromProducer step.
toConsumer step.
Returns
The consumer step.

Demuxer fan-out is not this operator. A demuxer binds one origin index at a time using the corresponding operator>> overload.

Analytics are configured separately through Filters.

Parameters
fromProducer step.
toConsumer step.
Returns
to.

◆ operator>> [7/7]

Demuxer & operator>> ( StormByte::Safe::Shared< class Plan > plan,
Demuxer & demuxer )
friend

Binds a plan to a demultiplexing stage.

Parameters
planPlan to bind.
demuxerStage receiving the plan.
Returns
The demultiplexing stage.

Binds a shared plan to a demultiplexing stage.

Parameters
planShared plan to bind.
demuxerStage receiving the plan.
Returns
The demultiplexing stage.
Parameters
planProvider-created intention owner.
demuxerDestination stage.
Returns
Destination stage.

◆ Plan

friend class Plan
friend

Allows the shared plan to wake registered stages.

◆ Remuxer

friend class Remuxer
friend

Allows the remultiplexing stage to access step internals.

◆ Route

friend class Route
friend

Allows route configuration to access step internals.

Member Data Documentation

◆ m_log

StormByte::Safe::Shared<StormByte::Logger::Log> StormByte::Multimedia::Pipeline::Step::m_log
protected

Scoped logger retained through Base-heap shared ownership.

◆ m_name

enum Producer StormByte::Multimedia::Pipeline::Step::m_name
protected

UseLog leaf / default Label.

◆ m_produces

Kinds StormByte::Multimedia::Pipeline::Step::m_produces
protected

Produces.

◆ m_receives

Kinds StormByte::Multimedia::Pipeline::Step::m_receives
protected

Receives.


The documentation for this class was generated from the following file:
  • lib/public/StormByte/multimedia/pipeline/step.hxx