From 0b5f070eae452081ae5c689e503e3b0ba85dc0ab Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Mon, 20 Apr 2009 15:55:09 +0200 Subject: [PATCH] design: add first version of stream-status Add the first version of the STREAM_STATUS message design docs. This message will be used to give applications more control over the streaming threads. --- docs/design/draft-stream-status.txt | 96 +++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/design/draft-stream-status.txt diff --git a/docs/design/draft-stream-status.txt b/docs/design/draft-stream-status.txt new file mode 100644 index 0000000..f8c7270 --- /dev/null +++ b/docs/design/draft-stream-status.txt @@ -0,0 +1,96 @@ +Stream Status +------------- + +This document describes the design and use cases for the stream status +messages. + +STREAM_STATUS messages are posted on the bus when the state of a streaming +thread changes. The purpose of this message is to allow the application to +interact with the streaming thread properties, such as the thread priority or +the threadpool to use. + +We accomodate for the following requirements: + + - Application is informed when a streaming thread is about to be created. + - Application is informed when the status of a streaming thread is changed. + - Application is informed when a streaming thread is destroyed. + +We allow for the following scenarios: + + - Elements require a specific (internal) streaming thread to operate or the + application can create/specify a thread for the element. + - Elements allow the application to configure a priority on the threads. + + +Use cases +--------- + + * boost the priority of the udp receiver streaming thread + + .--------. .-------. .------. .-------. + | udpsrc | | depay | | adec | | asink | + | src->sink src->sink src->sink | + '--------' '-------' '------' '-------' + + - when going from READY to PAUSED state, udpsrc will require a streaming + thread for pushing data into the depayloader. It will post a STREAM_STATUS + message indicating its requirement for a streaming thread. + + - The application will usually react to the STREAM_STATUS messages with a sync + bus handler. + + - The application can create and configure a custom GstTask to manage the + streaming thread or it can ignore the message which will make the element + use its default GstTask. + + - The application can react to the ENTER/LEAVE stream status message to + configure the thread right before it is started/stopped. This can be used to + configure the thread priority. + + - Before the GstTask is changed state (start/pause/stop) a STREAM_STATUS + message is posted that can be used by the application to keep track of + the running streaming threads. + + +Messages +-------- + + The existing STREAM_STATUS message will be further defined and implemented in + (selected) elements. The following fields will be contained in the message: + + - "status", GST_TYPE_STREAM_STATUS_TYPE + GST_STREAM_STATUS_TYPE_CREATE: a new streaming thread is going to be + created. The application has the chance to configure a custom thread. + GST_STREAM_STATUS_TYPE_ENTER: the streaming thread is about to enter its + loop function for the first time. + GST_STREAM_STATUS_TYPE_START: a streaming thread is started + GST_STREAM_STATUS_TYPE_PAUSE: a streaming thread is paused + GST_STREAM_STATUS_TYPE_STOP: a streaming thread is stopped + GST_STREAM_STATUS_TYPE_LEAVE: the streaming thread is about to leave its + loop. + GST_STREAM_STATUS_TYPE_DESTROY: a streaming thread is destroyed + + - "thread-object-type", GST_TYPE_THREAD_OBJECT + The type of object used for controlling the streaming thread. + GST_STREAM_THREAD_TASK: thread-object contains a GstTask object + controlling the streaming + GST_STREAM_THREAD_GTHREAD: threadobject contains a GThread that controls + the streaming. + + - "thread-object", GstTask/GThread + A GstTask/GThread controlling this streaming thread. This can be NULL when + the object controlling the streaming thread is not yet created. + + - "flow-return", GstFlowReturn + a status code for why the thread state changed. when threads are created + and started, this is usually GST_FLOW_OK but when they are stopping it + contains the reason why it stopped. + + +Events +------ + + + + + -- 2.7.4