Trait SourceLoop 

pub trait SourceLoop: ElementBound {
    type RunFuture<'a>: Future<Output = Result<u64, G2gError>> + 'a
       where Self: 'a;
    type CapsFuture<'a>: Future<Output = Result<Caps, G2gError>> + 'a
       where Self: 'a;

    // Required methods
    fn intercept_caps<'a>(&'a mut self) -> Self::CapsFuture<'a>;
    fn configure_pipeline(
        &mut self,
        absolute_caps: &Caps,
    ) -> Result<ConfigureOutcome, G2gError>;
    fn run<'a>(&'a mut self, out: &'a mut dyn OutputSink) -> Self::RunFuture<'a>;

    // Provided methods
    fn reconfigure(&mut self, _request: Reconfigure) -> Result<Caps, G2gError> { ... }
    fn latency(&self) -> LatencyReport { ... }
    fn output_memory(&self) -> MemoryDomainKind { ... }
    fn output_domains(&self) -> DomainSet { ... }
    fn query_duration(&self) -> Option<u64> { ... }
    fn configure_allocation(&mut self, _params: &AllocationParams) { ... }
    fn provide_clock(&self) -> Option<ClockCandidate> { ... }
    fn caps_constraint<'a>(
        &'a mut self,
    ) -> impl Future<Output = Result<CapsConstraint<'a>, G2gError>> + 'a { ... }
    fn caps_preferences(&self) -> Option<CapsPreferences> { ... }
    fn configured_output_caps(&self) -> Option<Caps> { ... }
    fn probe_output_caps(&mut self) -> Option<Caps> { ... }
    fn properties(&self) -> &'static [PropertySpec] { ... }
    fn metadata(&self) -> ElementMetadata { ... }
    fn set_instance_name(&mut self, _name: String) { ... }
    fn set_log_category(&mut self, _category: String) { ... }
    fn set_property(
        &mut self,
        _name: &str,
        _value: PropValue,
    ) -> Result<(), PropError> { ... }
    fn get_property(&self, _name: &str) -> Option<PropValue> { ... }
}

Source-side element trait. Sources have no input pad, so the packet-in / packet-out shape of AsyncElement does not fit them. A SourceLoop instead receives a single run call that iterates internally until EOS and returns the count of DataFrame packets pushed.

Required Associated Types

type RunFuture<'a>: Future<Output = Result<u64, G2gError>> + 'a where Self: 'a

type CapsFuture<'a>: Future<Output = Result<Caps, G2gError>> + 'a where Self: 'a

Future returned by [intercept_caps]. Async so a source can perform I/O during negotiation (e.g. RTSP DESCRIBE + SDP parse, hardware capability probe). Sources that produce caps without I/O can return core::future::Ready and the runner pays no cost.

Required Methods

fn intercept_caps<'a>(&'a mut self) -> Self::CapsFuture<'a>

Negotiation-time caps query. Awaited by the runner during startup (and on re-fixate retries). &mut self because real implementations (e.g. RtspSrc) open a session here and stash the connected state for run to resume from. Synchronous sources just return core::future::ready(Ok(caps)).

fn configure_pipeline( &mut self, absolute_caps: &Caps, ) -> Result<ConfigureOutcome, G2gError>

fn run<'a>(&'a mut self, out: &'a mut dyn OutputSink) -> Self::RunFuture<'a>

Runs the source until EOS or error. The implementation MUST emit a final PipelinePacket::Eos before returning Ok. Returns the number of DataFrame packets pushed (excluding Eos).

Provided Methods

fn reconfigure(&mut self, _request: Reconfigure) -> Result<Caps, G2gError>

Handle a downstream-originated Reconfigure request observed via PushOutcome::Reconfigure during run. Implementations that can retarget (eg picking a sub-stream over a main stream from an IP camera, or switching bitrate) return the new caps they will produce next; the source’s run loop is then responsible for emitting a CapsChanged packet and resuming under those caps.

Default: reject — most sources can’t change their output shape and FixationFailed propagates as a fatal pipeline error.

fn latency(&self) -> LatencyReport

This source’s latency contribution to the pipeline latency query (M12). Live capture sources (cameras, RTSP) override this to report live with their capture interval as min_ns; the default is zero, non-live (eg a file or test-pattern source that can produce data on demand).

fn output_memory(&self) -> MemoryDomainKind

The memory domain of the frames this source emits. Default System; a GPU capture source (a hardware decoder source emitting VRAM frames) overrides it. Surfaced per edge by the negotiate-only path for the DOT dump (it is not part of Caps).

fn output_domains(&self) -> DomainSet

The full set of memory domains this source can emit (M351). The producer-capability half of the two-sided allocation-domain negotiation; see AsyncElement::output_domains. Default: just output_memory. A GPU capture source that can also deliver to System overrides this.

fn query_duration(&self) -> Option<u64>

The total stream duration in nanoseconds, the source’s answer to the application DURATION query (M203). A source that knows the total length (a file / container source after reading its header, e.g. Mp4Src) overrides this; the runner publishes it on the PipelineProgress handle and posts a DurationChanged. The default None is “unknown” (a live / open-ended source, or one whose length is not yet parsed). Polled by the runner just before run.

fn configure_allocation(&mut self, _params: &AllocationParams)

Receive the downstream peer’s allocation proposal (M12) so the source can allocate its output BufferPool from compatible parameters (size, count, alignment, domain). Default: ignore and allocate the source’s own way. The proposal is advisory; a source that cannot honor it (eg cannot produce the requested domain) falls back silently.

fn provide_clock(&self) -> Option<ClockCandidate>

Offer a clock to the pipeline’s clock election (M12). Default: none. Live capture sources override this to provide their hardware capture clock at ClockPriority::LiveSource so the pipeline paces to capture cadence.

fn caps_constraint<'a>( &'a mut self, ) -> impl Future<Output = Result<CapsConstraint<'a>, G2gError>> + 'a

M16 step 5f: declare this source’s negotiation-time constraint. Default: eagerly await intercept_caps() and wrap as a LegacySource(Caps) for the solver. Migrated sources override to return Produces(CapsSet) (or another native variant) and the chain takes the native arc-consistency path when every other element is also native.

fn caps_preferences(&self) -> Option<CapsPreferences>

What this source is willing to pay for each alternative of the produce set its caps_constraint advertises. Default None: the alternatives are already in preference order and cost their index. A source overrides this to declare equal cost between formats it does not care about (so a downstream element’s preference decides) or a gap wide enough that a downstream preference cannot pull the chain onto its fallback.

fn configured_output_caps(&self) -> Option<Caps>

The fixed output caps this source already knows from its properties, readable synchronously without negotiation or I/O (M195). The auto-plug decodebin parser consults it to learn its upstream caps, so a property that re-types the output (a filesrc’s bytestream-format) is reflected into the chain search. The default None means “fall back to the registry’s declared caps”; a source whose output media type is property-driven overrides it. Returns None when the caps are only known at run time (e.g. bytestream-format=auto, which sniffs the file header).

fn probe_output_caps(&mut self) -> Option<Caps>

Like configured_output_caps but permitted to do I/O to determine the type (M480): the auto-plug decodebin parser calls this once, at parse time, to pick the demuxer. A bytestream-format= auto source overrides it to sniff the file header now (so a mislabeled .ts that is really an MP4 still auto-plugs the right demuxer, the way GStreamer’s runtime typefind would), where configured_output_caps returns None because it may not read. Default: the no-I/O caps.

fn properties(&self) -> &'static [PropertySpec]

The runtime properties this source type exposes (M104), the GObject property-spec analog. Default: none. A source overrides this (and set_property / get_property) to be settable by name from a gst-launch pipeline (eg filesrc location=..., videotestsrc pattern=...).

fn metadata(&self) -> ElementMetadata

Static introspection metadata for this source type (M178), the gst-inspect “Factory Details”. Default: empty.

fn set_instance_name(&mut self, _name: String)

Receive this source instance’s log name (M179), assigned by the runner. Default: ignore.

fn set_log_category(&mut self, _category: String)

Override this instance’s log category (M845), mirroring AsyncElement::set_log_category. Default: ignore. A source that logs about itself stores it in a LogName and returns it from LogSource::log_category_override.

fn set_property( &mut self, _name: &str, _value: PropValue, ) -> Result<(), PropError>

Set a property by name (M104). Default: PropError::Unknown.

fn get_property(&self, _name: &str) -> Option<PropValue>

Read a property back by name (M104). Default: None.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors