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.
Removing a track does not make its minted name available to Self::unique_name again.
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.
Subscribers wait on the name until it is accepted, so a reservation the producer
ends up never filling has to be dropped or rejected. Ending the broadcast
(Self::finish or Self::abort) resolves whatever is left.
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.
Uses Self::unique_name; minted names are never reused, even after removal or closure.
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 {id}{suffix} with an increasing ID shared across all suffixes and
producer clones in this broadcast, skipping names already in the lookup.
A digit-leading suffix gets a - separator so it cannot be confused with the ID.
Minted names are never reused, even if no track is created or it is removed or closed.
Explicit calls to Self::create_track can still reuse names.
§Panics
Panics if the broadcast exhausts its u64 IDs.
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.
A name that was reserved or requested but never served resolves with
Error::NotFound: nothing can fill it now, so its subscribers fail rather
than waiting on a track::Info that is never coming.
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), while a name nothing ever served resolves with err the same
way finish resolves it. 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.