pub struct Producer { /* private fields */ }Expand description
Manages tracks within a broadcast.
Create tracks up front with Self::create_track, reserve a name to fill in later with Self::reserve_track, or handle on-demand consumer requests via Self::dynamic.
§Lifetime
You must keep this producer alive for as long as the broadcast should stay
available. A broadcast lives as long as at least one Producer exists;
children do not keep it alive (cloning a Consumer or holding a
track::Producer does nothing for the broadcast’s lifetime). When the last
producer goes away every consumer observes Error::Dropped.
End the broadcast with Self::finish rather than dropping it. Dropping is an
easy footgun in garbage-collected bindings (Go, Python, …), where the handle
can be collected the moment it falls out of scope even while you are still
publishing, tearing the stream down mid-broadcast. Dropping the last producer
without Self::finish logs a warning.
Implementations§
Source§impl Producer
impl Producer
Sourcepub fn new(info: Info) -> Self
pub fn new(info: Info) -> Self
Create a producer for the given broadcast metadata. Prefer Info::produce.
Sourcepub fn remove_track(&mut self, name: &str) -> Result<(), Error>
pub fn remove_track(&mut self, name: &str) -> Result<(), Error>
Remove a track from the lookup.
Sourcepub fn create_track(
&mut self,
name: impl Into<Arc<str>>,
info: impl Into<Option<Info>>,
) -> Result<Producer, Error>
pub fn create_track( &mut self, name: impl Into<Arc<str>>, info: impl Into<Option<Info>>, ) -> Result<Producer, Error>
Produce a new track and insert it into the broadcast.
Pass a name and an optional track::Info, so a bare name works:
create_track("video", None).
Sourcepub fn reserve_track(
&mut self,
name: impl Into<Arc<str>>,
) -> Result<Request, Error>
pub fn reserve_track( &mut self, name: impl Into<Arc<str>>, ) -> Result<Request, Error>
Reserve a track by name without finalizing its track::Info.
Returns a track::Request already discoverable by consumers; call
track::Request::accept to set its info and start producing. Use this when
the producer can’t pick the track’s properties (e.g. timescale) until it has
inspected the media, the same shape as a consumer-driven
Dynamic::requested_track.
Sourcepub fn unique_track(
&mut self,
suffix: &str,
info: impl Into<Option<Info>>,
) -> Result<Producer, Error>
pub fn unique_track( &mut self, suffix: &str, info: impl Into<Option<Info>>, ) -> Result<Producer, Error>
Create a track with a unique name using the given suffix.
Generates names like 0{suffix}, 1{suffix}, etc. and picks the first
one not already used in this broadcast.
Sourcepub fn unique_name(&self, suffix: &str) -> String
pub fn unique_name(&self, suffix: &str) -> String
Generate a unique track name from a suffix without creating the track.
Returns a fresh name like 0{suffix}, 1{suffix}, etc. Use this when
you need to set non-default Track properties (e.g. with_timescale,
with_latency_max) before handing the Track to Self::create_track.
Sourcepub fn dynamic(&self) -> Dynamic
pub fn dynamic(&self) -> Dynamic
Create a dynamic producer that handles on-demand track requests from consumers.
Sourcepub fn set_route(&mut self, route: Route) -> Result<(), Error>
pub fn set_route(&mut self, route: Route) -> Result<(), Error>
Set the broadcast’s Route: the hop chain and cost it advertises.
Call this when the path to the content changes (an upstream failover) or the
publisher’s preference changes (e.g. a transcoder warming up lowers its
cost). Consumers observe the change via Consumer::route_changed and
sessions forward it downstream as a restart, never as a new broadcast.
Setting the current route again is a no-op.
Sourcepub fn consume(&self) -> Consumer
pub fn consume(&self) -> Consumer
Create a consumer that can subscribe to tracks in this broadcast.
Sourcepub fn finish(&mut self)
pub fn finish(&mut self)
Cleanly finish the broadcast once you are done publishing.
Marks the broadcast as deliberately finished so consumers observe a normal
end. Prefer this over dropping the producer: an accidental drop (see the note
on Producer) logs a warning, whereas finish() is silent.
Ends the broadcast outright: consumers observe a normal end immediately and no new tracks are served, whether or not other producer clones are still alive. Existing tracks stay readable so consumers can drain what they already have.
Borrows rather than consumes, matching track::Producer::finish. Finishing
declares the end, so it must not depend on the caller also surrendering the
handle.
Sourcepub fn abort(self, err: Error) -> Result<(), Error>
pub fn abort(self, err: Error) -> Result<(), Error>
Abort the broadcast, ending it for consumers with err.
Like finish the end is immediate, whether or not other
producer clones are still alive, and existing tracks stay readable so
consumers can drain what they already have (an abort does not cascade into
the tracks). Unlike a finish, consumers observe err from
Consumer::closed, and an origin treats the source as ungracefully lost,
so the path may linger for a replacement (see
origin::Info::linger).
Consumes the producer: an abort is terminal. Errors if the broadcast was already finished or aborted.