public Event.qos (QOSType type, double proportion, ClockTimeDiff diff, ClockTime timestamp)
Allocate a new qos event with the given values.
The QOS event is generated in an element that wants an upstream element to either reduce or increase its rate because of high/low CPU load or other resource usage such as network performance or throttling. Typically sinks generate these events for each buffer they receive.
type indicates the reason for the QoS event. OVERFLOW is
used when a buffer arrived in time or when the sink cannot keep up with the upstream datarate.
UNDERFLOW is when the sink is not receiving buffers fast enough and
thus has to drop late buffers. THROTTLE is used when the datarate is
artificially limited by the application, for example to reduce power consumption.
proportion indicates the real-time performance of the streaming in the element that generated the QoS event (usually the sink).
The value is generally computed based on more long term statistics about the streams timestamps compared to the clock. A value < 1.0
indicates that the upstream element is producing data faster than real-time. A value > 1.0 indicates that the upstream element is not
producing data fast enough. 1.0 is the ideal
proportion value. The proportion value can safely be used to lower or increase the
quality of the element.
diff is the difference against the clock in running time of the last buffer that caused the element to generate the QOS event. A
negative value means that the buffer with
timestamp arrived in time. A positive value indicates how late the buffer with
timestamp was. When throttling is enabled,
diff will be set to the requested throttling interval.
timestamp is the timestamp of the last buffer that cause the element to generate the QOS event. It is expressed in running time
and thus an ever increasing value.
The upstream element can use the
timestamp values to decide whether to process more buffers. For positive
diff, all buffers with timestamp <=
diff will certainly arrive late in the sink as well. A
diff value so that
diff would yield a result smaller than 0 is not allowed.
The application can use general event probes to intercept the QoS event and implement custom application specific QoS handling.
the QoS type
the proportion of the qos message
The time difference of the last Clock sync
The timestamp of the buffer
a new QOS event.