View Source Membrane.RTC.Engine.Endpoint.WebRTC.ConnectionAllocator behaviour (Membrane RTC Engine WebRTC Endpoint v0.1.0)
Behavior defining a set of functions for managing connection allocations for TrackReceivers.
It is responsible for allocating connection bandwidth for track receivers and probing the connection.
Message protocol
In addition to implementing the behavior, Each implementation of ConnectionAllocator should be aware of the following message protocol.
Membrane.RTC.Engine.Endpoint.WebRTC.TrackReceiver already implements proper handling of this message protocol.
Granting an allocation
Membrane.RTC.Engine.Endpoint.WebRTC.ConnectionAllocator.AllocationGrantedNotification.t/0 message is sent to TrackReceiver when ConnectionAllocator
wants to grant an allocation. TrackReceiver is obligated to comply. This message can also be used to
force-lower the allocation of a particular TrackReceiver, skipping the negotiation flow.
Negotiating lower allocation
Whenever it is deemed necessary, ConnectionAllocator can send decrease_allocation_request/0 to
selected TrackReceiver, to request that it lowers its allocation by unspecified amount.
Usually, this will mean that TrackReceiver selects a lower variant (if possible).
In response, TrackReceiver sends decrease_allocation_request_response/0 to ConnectionAllocator.
If the request was accepted, TrackReceiver is obligated to request lower allocation
immediately after sending a reply.
Example of decrease allocation request message flow
CA - Connection Allocator
TR - Track Receiver
CA -> TR: :decrease_your_allocation
TR -> CA: {:decrease_allocation_request, :accept}
TR calls `request_allocation/2` with lowered allocation
CA -> AllocationGrantedNotificationSummary
Types
Type describing a message sent by ConnectionAllocator to Membrane.RTC.Engine.Endpoint.WebRTC.TrackReceiver
to request that they lower their allocation.
Type describing a message sent by Membrane.RTC.Engine.Endpoint.WebRTC.TrackReceiver to ConnectionAllocator
in response to decrease_allocation_request/0, in order to either accept or reject the request.
Callbacks
Function invoked by the TrackReceiver whenever a buffer is sent
A function that should be used by the WebRTC Endpoint to create an instance of ConnectionAllocator
A function that should be used by the endpoint to destroy an instance of ConnectionAllocator
Function called by the TrackReceiver to register itself in the allocator
A function used by the VariantSelector to request a different bandwidth allocation.
Function used to change the negotiability status of the TrackReceiver.
A function called by the endpoint, to update the bandwidth estimation in the allocator
Types
@type allocator_ref() :: any()
@type decrease_allocation_request() :: :decrease_your_allocation
Type describing a message sent by ConnectionAllocator to Membrane.RTC.Engine.Endpoint.WebRTC.TrackReceiver
to request that they lower their allocation.
@type decrease_allocation_request_response() ::
{:decrease_allocation_request, :accept | :reject}
Type describing a message sent by Membrane.RTC.Engine.Endpoint.WebRTC.TrackReceiver to ConnectionAllocator
in response to decrease_allocation_request/0, in order to either accept or reject the request.
Callbacks
@callback buffer_sent(allocator_ref(), Membrane.Buffer.t()) :: :ok
Function invoked by the TrackReceiver whenever a buffer is sent
@callback create() :: {:ok, allocator_ref()} | {:error, reason :: any()}
A function that should be used by the WebRTC Endpoint to create an instance of ConnectionAllocator
@callback destroy(allocator_ref()) :: :ok
A function that should be used by the endpoint to destroy an instance of ConnectionAllocator
@callback register_track_receiver( allocator_ref(), number(), Membrane.RTC.Engine.Track.t(), Keyword.t() ) :: :ok
Function called by the TrackReceiver to register itself in the allocator
@callback request_allocation(allocator_ref(), number()) :: :ok
A function used by the VariantSelector to request a different bandwidth allocation.
In response, the Allocator sends Membrane.RTC.Engine.Endpoint.WebRTC.ConnectionAllocator.AllocationGrantedNotification
to the track receiver that gets new allocation.
@callback set_negotiability_status(allocator_ref(), boolean()) :: :ok
Function used to change the negotiability status of the TrackReceiver.
TrackReceiver is considered negotiable if it is both capable of decreasing its bandwidth usage and, in principal, allowed to do so.
@callback update_bandwidth_estimation(allocator_ref(), number()) :: :ok
A function called by the endpoint, to update the bandwidth estimation in the allocator