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

@@ -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
+------
+
+
+
+
+