One stage with a Backend::Pipeline::Pipe (in / out). More...

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

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

[legend]

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

[legend]

Classes
class	Join
	Last data member of every most-derived Step. More...

Public Member Functions
Lifecycle
	Step (const Step &other)=delete
	Step (Step &&other) noexcept=delete
virtual	~Step () noexcept
	Destructor.
Step &	operator= (const Step &other)=delete
Step &	operator= (Step &&other) noexcept=delete
Sinks
std::condition_variable &	Wake () noexcept
	Consumer condition variable.
Plan
const std::shared_ptr< 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.
virtual bool	Ready () const noexcept
	Whether this step can take work.
void	Stop () noexcept
	Asks the worker to leave and closes all hoppers.
virtual std::size_t	InputCeiling () const noexcept
	Ceiling of this step's input hopper.
Failure
bool	Failed () const noexcept
	Whether this step has failed.
const std::optional< std::string > &	Error () const noexcept
	Failure text.
void	Fail (std::string reason) noexcept
	Marks Failed, closes all hoppers and wakes the worker.

Protected Member Functions
Backend::Pipeline::Pipe &	pipe () noexcept
	In / out hoppers of this stage.
const Backend::Pipeline::Pipe &	pipe () const noexcept
	In / out hoppers of this stage.
Construction
	Step (std::shared_ptr< StormByte::Logger::Log > log, enum Producer name, Kinds receives, Kinds produces) noexcept
	Step in State::Created.
Work
void	Emit (Item::PointerType item) noexcept
	Write `item` to the Pipe (`item` >> pipe).
Item::PointerType	CloneItem (const Item &item) const noexcept
	Deep-copies `item` through Item::Clone.
virtual void	Wait () noexcept
	Sleeps on Wake until hopper Ready, Failed, Stopping 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 the pumper: Setup, Ready, Pump.
void	Halt () noexcept
	Stop and join the pumper.
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
	Owner surface for the Pumper and Worker.
void	Mount (std::unique_ptr< Backend::Pipeline::Pumper > pumper, std::unique_ptr< Backend::Pipeline::Worker > worker) noexcept
	Takes ownership of `pumper` and binds `worker`.
Logging
virtual std::string	Label () const noexcept
	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
std::shared_ptr< StormByte::Logger::Log >	m_log
	Scoped module logger (ThreadedLog preferred).
enum Producer	m_name
	UseLog leaf / default Label.
Kinds	m_receives
	Receives.
Kinds	m_produces
	Produces.

Friends
class	Demuxer
class	Muxer
class	Remuxer
class	Route
class	Filters
Decoder &	operator>> (Demuxer &demuxer, Decoder &decoder)
	Binds one origin track of `demuxer` to `decoder`.
Demuxer &	operator>> (class Plan &&plan, Demuxer &demuxer)
	Hands `plan` to `demuxer`.
Encoder &	operator>> (Encoder &encoder, Muxer &muxer)
	Reserves `encoder` as an output track of `muxer`.
Muxer &	operator>> (Demuxer &demuxer, Muxer &muxer)
	Binds `demuxer` as remux origin and forwards its attachments.
Remuxer &	operator>> (Demuxer &demuxer, Remuxer &remuxer)
	Binds origin track remuxer.In() from `demuxer` onto `remuxer`.
Remuxer &	operator>> (Remuxer &remuxer, Muxer &muxer)
	Reserves `remuxer` as an output track of `muxer`.
Step &	operator>> (Step &from, Step &to)
	Shares Plan and binds every output hopper of `from` onto `to`.

Detailed Description

One stage with a Backend::Pipeline::Pipe (in / out).

Owns a Pumper (thread + State) and exposes hoppers to that pumper through a private Host surface. Leaves Mount a concrete Pumper and Worker, then Launch.

Log lines use Scope StormByte/Multimedia/<Producer>. UseLog installs the module format and throttle. Volume is that Logger throttle, not a per-step counter.

Emit writes item >> pipe. Analytics looks are a Backend::Pipeline::Pipe::CloneTo on that Pipe, bound by Filters before the origin emits. Without CloneTo there is no clone.

Constructor & Destructor Documentation

◆ Step() [1/3]

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

delete

◆ Step() [2/3]

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

deletenoexcept

◆ ~Step()

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

virtualnoexcept

Destructor.

Joins the pumper if Launch ran.

Most-derived Step members are already gone. Those leaves Halt first via Join so a backend the worker still uses survives until the thread has left.

◆ Step() [3/3]

StormByte::Multimedia::Pipeline::Step::Step	(	std::shared_ptr< StormByte::Logger::Log >	log,
		enum Producer	name,
		Kinds	receives,
		Kinds	produces )

protectednoexcept

Step in State::Created.

Sinks start at zero buckets.

Parameters

log	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. UseLog leaf and default Label.
receives	Kinds this step consumes.
produces	Kinds 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

protectednoexcept

Deep-copies item through Item::Clone.

Parameters

item	Unit to clone.

Returns: Owning pointer, or empty if item cannot clone.

Packet/Frame copy constructors stay private. Looks must go through this helper (or Emit) so a leaf Step does not need to be a friend of the unit types.

◆ 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

Write item to the Pipe (item >> pipe).

Parameters

item	Unit to emit. Empty is a no-op.

Analytics clones, if any, happen inside the Pipe after Backend::Pipeline::Pipe::CloneTo.

◆ Error()

const std::optional< std::string > & StormByte::Multimedia::Pipeline::Step::Error ( ) const

noexcept

Failure text.

Returns: Message, or empty.

◆ Face()

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

protectednoexcept

Owner surface for the Pumper and Worker.

Returns: Host implemented by this Step.

◆ Fail()

void StormByte::Multimedia::Pipeline::Step::Fail ( std::string reason )

noexcept

Marks Failed, closes all hoppers and wakes the worker.

Bound neighbors unblock on hopper EoF. Does not join the worker; the worker may be the caller. Does not write a log line; the owner of the job logs Error.

Parameters

reason Message.

◆ 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

Stop and join the pumper.

Safe to call more than once. Step leaves do not call this from their destructor: Join is their last member and Halt s before other members die. Filter plugins never call Halt; Route joins them while the leaf is still complete.

◆ InputCeiling()

virtual std::size_t StormByte::Multimedia::Pipeline::Step::InputCeiling ( ) const

virtualnoexcept

Ceiling of this step's input hopper.

Returns: Max queued items. 0 means unbounded.

Leaves override this and return their private Ceiling. Bind sites call it after creating the destination bucket.

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

◆ Label()

virtual std::string StormByte::Multimedia::Pipeline::Step::Label ( ) const

protectedvirtualnoexcept

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 the pumper: Setup, Ready, Pump.

Idempotent. No-op without a mounted pumper, 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

level	StormByte::Logger::Level of this line.
message	Already-formatted text (caller may use std::format). Must not include the level name; Logger prints that.

No-op when m_log is empty. Virtual so a leaf can re-expose it to its backend (friendship is not inherited). c is StormByte/Multimedia/<leaf>. There is no STMM component and no Logger group.

◆ Mount()

void StormByte::Multimedia::Pipeline::Step::Mount	(	std::unique_ptr< Backend::Pipeline::Pumper >	pumper,
		std::unique_ptr< Backend::Pipeline::Worker >	worker )

protectednoexcept

Takes ownership of pumper and binds worker.

Parameters

pumper	Source, Through or Sink. Must not be empty.
worker	Stage body. Must not be empty.

No-op if a pumper is already mounted. Does not Launch.

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

deletenoexcept

◆ pipe() [1/2]

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

protectednoexcept

In / out hoppers of this stage.

Returns: The composed Pipe.

◆ pipe() [2/2]

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

protectednoexcept

In / out hoppers of this stage.

Returns: The composed Pipe.

◆ Plan()

const std::shared_ptr< class Plan > & StormByte::Multimedia::Pipeline::Step::Plan ( ) const

inlinenoexcept

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.

◆ Ready()

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

virtualnoexcept

Whether this step can take work.

Default: Status is Ready (Setup finished without Fail or Stop). Muxer also requires Muxer::Armed so header write and Pump do not start while operator>> is still reserving.

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

microseconds Wall 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

Asks the worker to leave and closes all hoppers.

Neighbors unblock on hopper EoF. Does not join; the worker may be the caller. Idempotent. A mounted tube is not restarted after Stop.

◆ 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.

◆ Wait()

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

protectedvirtualnoexcept

Sleeps on Wake until hopper Ready, Failed, Stopping or WakeNow.

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

◆ Wake()

std::condition_variable & StormByte::Multimedia::Pipeline::Step::Wake ( )

noexcept

Consumer condition variable.

Returns: The single CV of this step.

◆ WakeNow()

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

protectedvirtualnoexcept

Extra reason to leave Wait.

Returns: true to wake without hopper Ready. Default false.

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

◆ Demuxer

friend class Demuxer

friend

◆ Filters

friend class Filters

friend

◆ Muxer

friend class Muxer

friend

◆ operator>> [1/7]

Demuxer & operator>>	(	class Plan &&	plan,
		Demuxer &	demuxer )

friend

Hands plan to demuxer.

Not a Step bind.

Parameters

plan	Intention (moved).
demuxer	Destination.

Returns: demuxer.

Stores the Plan on the Demuxer and wakes it. Does not call Plan::Check and does not bind hoppers.

◆ operator>> [2/7]

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

friend

Binds one origin track of demuxer to decoder.

Parameters

demuxer	Origin demuxer.
decoder	Destination decoder.

Returns: decoder.

◆ operator>> [3/7]

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

friend

Binds demuxer as remux origin and forwards its attachments.

Required when any remux track is reserved. Without it the muxer cannot clone origin codec parameters. Also shares the tube Progress clock.

Parameters

demuxer	Origin demuxer. Must outlive header write.
muxer	Destination.

Returns: muxer.

◆ operator>> [4/7]

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

friend

Binds origin track remuxer.In() from demuxer onto remuxer.

Parameters

demuxer	Origin demuxer.
remuxer	Destination remuxer.

Returns: remuxer.

◆ operator>> [5/7]

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

friend

Reserves encoder as an output track of muxer.

Parameters

encoder	Live encoder.
muxer	Destination.

Returns: encoder.

◆ operator>> [6/7]

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

friend

Reserves remuxer as an output track of muxer.

Parameters

remuxer	Live remuxer.
muxer	Destination.

Returns: remuxer.

◆ operator>> [7/7]

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

friend

Shares Plan and binds every output hopper of from onto to.

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

Does not bind the analytics tap.

Parameters

from	Producer step.
to	Consumer step.

Returns: to.

◆ Remuxer

friend class Remuxer

friend

◆ Route

friend class Route

friend

Member Data Documentation

◆ m_log

std::shared_ptr<StormByte::Logger::Log> StormByte::Multimedia::Pipeline::Step::m_log

protected

Scoped module logger (ThreadedLog preferred).

◆ 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

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Step() [1/3]

◆ Step() [2/3]

◆ ~Step()

◆ Step() [3/3]

Member Function Documentation

◆ AfterWait()

◆ CloneItem()

◆ DumpWork()

◆ Emit()

◆ Error()

◆ Face()

◆ Fail()

◆ Failed()

◆ Halt()

◆ InputCeiling()

◆ Label()

◆ LastWork()

◆ Launch()

◆ Log()

◆ Mount()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pipe() [1/2]

◆ pipe() [2/2]

◆ Plan()

◆ Produces()

◆ Ready()

◆ Receives()

◆ RecordWork()

◆ Status()

◆ Stop()

◆ Stopping()

◆ Wait()

◆ Wake()

◆ WakeNow()

Friends And Related Symbol Documentation

◆ Demuxer

◆ Filters

◆ Muxer

◆ operator>> [1/7]

◆ operator>> [2/7]

◆ operator>> [3/7]

◆ operator>> [4/7]

◆ operator>> [5/7]

◆ operator>> [6/7]

◆ operator>> [7/7]

◆ Remuxer

◆ Route

Member Data Documentation

◆ m_log

◆ m_name

◆ m_produces

◆ m_receives