A pipeline stage that receives and emits media items. More...
#include <StormByte/multimedia/pipeline/step.hxx>


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. | |
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.
|
delete |
Copy construction is disabled.
| other | Source stage. |
|
deletenoexcept |
Move construction is disabled.
| other | Source stage. |
|
virtualnoexcept |
Destructor.
Waits for stage execution to finish.
|
protected |
Constructs a stage in State::Created.
| log | Base-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. |
| name | Stage name for log scope and default Label. |
| receives | Kinds this step consumes. |
| produces | Kinds this step emits. |
|
protectedvirtualnoexcept |
Work on the waiting worker after Wait unblocks.
Default no-op. Leaf office.
|
protected |
Creates a distinct item through Item::Clone.
| item | Unit to clone. |
item cannot clone.Media buffers are shared according to Item::Clone; the returned item does not duplicate the media payload.
|
protectednoexcept |
Registers a borrowed downstream stage and shares any bound plan.
| downstream | Stage retained by the graph owner until assembly and execution end. |
|
protectednoexcept |
Writes min/max Process time at Debug.
No-op if none.
|
protectednoexcept |
Sends item to connected consumers.
| item | Unit to emit. Empty is a no-op. |
Configured analytics receive copies without changing item.
| StormByte::Safe::Optional< StormByte::Safe::String > StormByte::Multimedia::Pipeline::Step::Error | ( | ) | const |
Failure text.
|
protectednoexcept |
|
noexcept |
Marks failure without storing a message or allocating.
|
inlinenoexcept |
Copies a null-terminated failure literal into Safe storage.
| reason | Message literal; null becomes an empty message. |
|
noexcept |
Copies borrowed failure text before calling the DLL-safe overload.
| reason | Borrowed message, used only during this call. |
|
noexcept |
|
noexcept |
Whether this step has failed.
|
protectednoexcept |
|
virtualnoexcept |
Maximum number of queued input items.
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.
|
protectedvirtual |
|
protectednoexcept |
Duration of the last timed Process, or 0.
|
protectednoexcept |
Starts stage initialization and processing.
Idempotent. No-op without an execution handler, or if the stage has already Failed or Stopped.
|
protectedvirtualnoexcept |
Writes one log line on the scoped module logger.
| level | StormByte::Logger::Level of this line. |
| message | Already-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.
|
protected |
Copy assignment is disabled.
| other | Source stage. |
Move assignment is disabled.
| other | Source stage. |
|
protectednoexcept |
|
protectednoexcept |
|
noexcept |
Bound job intention, if any.
|
inlinenoexcept |
Kinds this step emits.
|
noexcept |
Reads effective queue limits and logical-byte accounting.
| track | Input track key. |
Read the requested policy from Plan::Buffering. Snapshot byte weights are logical estimates, not physical memory or RSS.
|
virtualnoexcept |
Whether this step can take work.
By default, Status must be State::Ready. Muxer also requires Muxer::Armed before writing output.
Reimplemented in StormByte::Multimedia::Pipeline::Muxer.
|
inlinenoexcept |
Kinds this step consumes.
|
protectednoexcept |
Adds one Process duration to the step summary.
| microseconds | Wall time of that Process call. |
|
noexcept |
Current lifecycle value.
|
noexcept |
Requests shutdown and notifies connected stages.
Returns without waiting for completion. Safe to call more than once. A stopped stage cannot be restarted.
|
protectednoexcept |
Worker must return (Stop, Halt or Fail).
| 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.
|
protectedvirtualnoexcept |
|
protectednoexcept |
Waits interruptibly for the shared plan to enter Running.
|
noexcept |
Notifies all waiters of this step.
|
protectedvirtualnoexcept |
|
friend |
Allows topology telemetry to read the queue probe.
|
friend |
Allows the demultiplexing stage to access step internals.
|
friend |
Allows filter configuration to access step internals.
|
friend |
Allows the multiplexing stage to access step internals.
Connects a demultiplexing stage to a decoding stage.
| demuxer | Producer stage. |
| decoder | Consumer stage. |
| demuxer | Origin demuxer. |
| decoder | Destination decoder. |
decoder. Connects a demultiplexing stage to a multiplexing stage.
| demuxer | Producer stage. |
| muxer | Consumer 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.
| demuxer | Origin demuxer. Must outlive header write. |
| muxer | Destination. |
muxer. Connects a demultiplexing stage to a remultiplexing stage.
| demuxer | Producer stage. |
| remuxer | Consumer stage. |
Connect the origin demuxer to this remuxer.
| demuxer | Origin demuxer. |
| remuxer | Destination remuxer. |
remuxer. Connects an encoding stage to a multiplexing stage.
| encoder | Producer stage. |
| muxer | Consumer stage. |
Allows encoder connections to reserve output tracks.
| encoder | Live encoder. |
| muxer | Destination. |
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.
Connects a remultiplexing stage to a multiplexing stage.
| remuxer | Producer stage. |
| muxer | Consumer stage. |
Connect this remuxer to the destination muxer.
Allows remuxer connections to reserve output tracks.
| remuxer | Live remuxer. |
| muxer | Destination. |
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.
Connects output from one step to another.
| from | Producer step. |
| to | 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.
| from | Producer step. |
| to | Consumer step. |
to.
|
friend |
Binds a plan to a demultiplexing stage.
| plan | Plan to bind. |
| demuxer | Stage receiving the plan. |
Binds a shared plan to a demultiplexing stage.
| plan | Shared plan to bind. |
| demuxer | Stage receiving the plan. |
| plan | Provider-created intention owner. |
| demuxer | Destination stage. |
|
friend |
Allows the shared plan to wake registered stages.
|
friend |
Allows the remultiplexing stage to access step internals.
|
friend |
Allows route configuration to access step internals.
|
protected |
Scoped logger retained through Base-heap shared ownership.
|
protected |
UseLog leaf / default Label.
|
protected |
Produces.
|
protected |
Receives.