From da14267ea8bf1c6046f450f09547d0661bca666e Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 3 Jun 2011 17:24:21 +0200 Subject: [PATCH] docs: first version of probes document --- docs/design/part-probes.txt | 230 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 docs/design/part-probes.txt diff --git a/docs/design/part-probes.txt b/docs/design/part-probes.txt new file mode 100644 index 0000000..8eb97cd --- /dev/null +++ b/docs/design/part-probes.txt @@ -0,0 +1,230 @@ +Probes +------ + + Probes are callbacks that can be installed by the application and will notify + the application about the states of the dataflow. + + +Requirements +------------ + +Applications should be able to monitor and control the dataflow on pads. We +identify the following types: + + - be notified when the pad is/becomes idle and make sure the pad stays idle. + This is essential to be able to implement dynamic relinking of elements + without breaking the dataflow. + + - be notified when data or events are pushed or sent on a pad. It should also + be possible to inspect and modify the data. + + - be able to drop, pass and block on data based on the result of the callback. + + - be able to drop, pass data on blocking pads based on methods performed by + the application thread. + + +Overview +-------- + + The function gst_pad_add_probe() is used to add a probe to a pad. It accepts a + probe type mask and a callback. + + gulong gst_pad_add_probe (GstPad *pad, + GstProbeType mask, + GstPadProbeCallback callback, + gpointer user_data, + GDestroyNotify destroy_data); + + The function returns a gulong that uniquely identifies the probe and that can + be used to remove the probe with gst_pad_remove_probe(): + + void gst_pad_remove_probe (GstPad *pad, gulong id); + + The mask parameter is a bitwise or of the following flags: + + typedef enum + { + GST_PROBE_TYPE_INVALID = 0, + + /* flags to control blocking */ + GST_PROBE_TYPE_IDLE = (1 << 0), + GST_PROBE_TYPE_BLOCK = (1 << 1), + + /* flags to select datatypes */ + GST_PROBE_TYPE_BUFFER = (1 << 2), + GST_PROBE_TYPE_BUFFER_LIST = (1 << 3), + GST_PROBE_TYPE_EVENT = (1 << 4), + + /* flags to select scheduling mode */ + GST_PROBE_TYPE_PUSH = (1 << 5), + GST_PROBE_TYPE_PULL = (1 << 6), + } GstProbeType; + + When adding a probe with the IDLE or BLOCK flag, the probe will become a + blocking probe (see below). Otherwise the probe will be a DATA probe. + + The datatype and scheduling selector flags are used to select what kind of + datatypes and scheduling modes should be allowed in the callback. + + The blocking flags must match the triggered probe exactly. + + The probe callback is defined as: + + GstProbeReturn (*GstPadProbeCallback) (GstPad *pad, GstProbeType type, + gpointer type_data, + gpointer user_data); + + The executing probe type is passed as an argument and is guaranteed to match + the mask that was used to register the callback. type_data contains type + specific data, which is usually the data item that is blocked or NULL when + no data item is present. + + The probe can return any of the following return values: + + typedef enum + { + GST_PROBE_DROP, + GST_PROBE_OK, + GST_PROBE_REMOVE, + GST_PROBE_PASS, + } GstProbeReturn; + + GST_PROBE_OK is the normal return value. DROP will drop the item that is + currently being probed. GST_PROBE_REMOVE the currently executing probe from the + list of probes. + + GST_PROBE_PASS is relevant for blocking probes and will temporarily unblock the + pad and let the item trough, it will then block again on the next item. + + +Blocking probes +--------------- + + Blocking probes are probes with BLOCK or IDLE flags set. They will always + block the dataflow and trigger the callback according to the following rules: + + When the IDLE flag is set, the probe callback is called as soon as no data is + flowing over the pad. If at the time of probe registration, the pad is idle, + the callback will be called immediately from the current thread. Otherwise, + the callback will be called as soon as the pad becomes idle in the streaming + thread. + + The IDLE probe in useful to perform dynamic linking, it allows to wait for for + a safe moment when an unlink/link operation can be done. Since the event is a + blocking event, it will also make sure that the pad stays idle until the probe + is removed. + + When the BLOCK flag is set, the probe callback will be called when new data + arrives on the pad and right before the pad goes into the blocking state. This + callback is thus only called when there is new data on the pad. + + The blocking probe is removed with gst_pad_remove_probe() or when the probe + callback return GST_PROBE_REMOVE. In both cases, and if this was the last + blocking probe on the pad, the pad is unblocked and dataflow can continue. + + +Non-Blocking probes +-------------------- + + Non-blocking probes or DATA probes are probes triggered when data is flowing + over the pad. The are called after the blocking probes are run and always with + data. + + +Push dataflow +------------- + +All probes have the GST_PROBE_TYPE_PUSH flag set in the callbacks. + +In push based scheduling, the blocking probe is called first with the DATA item. +Then the data probes are called before the peer pad chain function is called. + +The data probes are called before the peer pad is checked. This allows for +linking the pad in either the BLOCK or DATA probes on the srcpad. + +Before the sinkpad chain function is called, the data probes are called. + +Finally, the IDLE probe is called on the srcpad after the data was sent to the +peer pad. + + + srcpad sinkpad + | | + gst_pad_push() | | + -------------->O | + O | + flushing? O | + WRONG_STATE O | + < - - - - - - O | + O-> do BLOCK probes | + O | + O-> do DATA probes | + no peer? O | + NOT_LINKED O | + < - - - - - - O | + O gst_pad_chain() | + O------------------------------>O + O flushing? O + O WRONG_STATE O + O< - - - - - - - - - - - - - - -O + O O-> do DATA probes + O O + O O---> chainfunc + O< - - - - - - - - - - - - - - -O + O | + O-> do IDLE probes | + O | + < - - - - - - O | + | | + + +Pull dataflow +------------- + +All probes have the GST_PROBE_TYPE_PULL flag set in the callbacks. + +The gst_pad_pull_range() call will first trigger the BLOCK probes without a DATA +item. This allows the pad to be linked before the peer pad is resolved. + +After the getrange function is called on the peer pad and there is a data item, +the DATA probes are called. + +When control returns to the sinkpad, the IDLE callbacks are called. + +It there is a valid DATA item, the DATA probes are called for the item. + + + srcpad sinkpad + | | + | | gst_pad_pull_range() + | O<--------------------- + | O + | O flushing? + | O WRONG_STATE + | O - - - - - - - - - - > + | do BLOCK probes <-O + | O no peer? + | O NOT_LINKED + | O - - - - - - - - - - > + | gst_pad_get_range() O + O<------------------------------O + O O + O flushing? O + O WRONG_STATE O + O- - - - - - - - - - - - - - - >O + getrangefunc <---O O + O flow error? O + O- - - - - - - - - - - - - - - >O + O O + dp DATA probes <-O O + O- - - - - - - - - - - - - - - >O + | O + | do IDLE probes <-O + | O flow error? + | O - - - - - - - - - - > + | O + | do DATA probes <-O + | O - - - - - - - - - - > + | | + -- 2.7.4