docs/design/part-stream-status.txt

   1 Stream Status
   2 -------------
   3
   4 This document describes the design and use cases for the stream status
   5 messages.
   6
   7 STREAM_STATUS messages are posted on the bus when the state of a streaming
   8 thread changes. The purpose of this message is to allow the application to
   9 interact with the streaming thread properties, such as the thread priority or
  10 the threadpool to use.
  11
  12 We accommodate for the following requirements:
  13
  14  - Application is informed when a streaming thread is about to be created. It
  15    should be possible for the application to suggest a custom GstTask.
  16  - Application is informed when the status of a streaming thread is changed.
  17    This can be interesting for GUI application that want to visualize the status
  18    of the streaming threads (playing/paused/stopped)
  19  - Application is informed when a streaming thread is destroyed.
  20
  21 We allow for the following scenarios:
  22
  23  - Elements require a specific (internal) streaming thread to operate or the
  24    application can create/specify a thread for the element.
  25  - Elements allow the application to configure a priority on the threads.
  26
  27
  28 Use cases
  29 ~~~~~~~~~
  30
  31  * boost the priority of the udp receiver streaming thread
  32
  33     .--------.    .-------.    .------.    .-------.
  34     | udpsrc |    | depay |    | adec |    | asink |
  35     |       src->sink    src->sink   src->sink     |
  36     '--------'    '-------'    '------'    '-------'
  37
  38   - when going from READY to PAUSED state, udpsrc will require a streaming
  39     thread for pushing data into the depayloader. It will post a STREAM_STATUS
  40     message indicating its requirement for a streaming thread.
  41
  42   - The application will usually react to the STREAM_STATUS messages with a sync
  43     bus handler.
  44
  45   - The application can create and configure a custom GstTask to manage the
  46     streaming thread or it can ignore the message which will make the element
  47     use its default GstTask.
  48
  49   - The application can react to the ENTER/LEAVE stream status message to
  50     configure the thread right before it is started/stopped. This can be used to
  51     configure the thread priority.
  52
  53   - Before the GstTask is changed state (start/pause/stop) a STREAM_STATUS
  54     message is posted that can be used by the application to keep track of
  55     the running streaming threads.
  56
  57
  58 Messages
  59 ~~~~~~~~
  60
  61  The existing STREAM_STATUS message will be further defined and implemented in
  62  (selected) elements. The following fields will be contained in the message:
  63
  64   - "type", GST_TYPE_STREAM_STATUS_TYPE
  65
  66       - a set of types to control the lifecycle of the thread:
  67        GST_STREAM_STATUS_TYPE_CREATE: a new streaming thread is going to be
  68           created. The application has the chance to configure a custom thread.
  69        GST_STREAM_STATUS_TYPE_ENTER: the streaming thread is about to enter its
  70           loop function for the first time.
  71        GST_STREAM_STATUS_TYPE_LEAVE: the streaming thread is about to leave its
  72           loop.
  73        GST_STREAM_STATUS_TYPE_DESTROY: a streaming thread is destroyed
  74
  75       - A set of types to control the state of the threads:
  76        GST_STREAM_STATUS_TYPE_START: a streaming thread is started
  77        GST_STREAM_STATUS_TYPE_PAUSE: a streaming thread is paused
  78        GST_STREAM_STATUS_TYPE_STOP: a streaming thread is stopped
  79
  80   - "owner", GST_TYPE_ELEMENT
  81       The owner element of the thread. The message source will contain the pad
  82       (or one of the pads) that will produce data by this thread. If this thread
  83       does not produce data on a pad, the message source will contain the owner
  84       as well. The idea is that the application should be able to see from the
  85       element/pad what function this thread has in the context of the
  86       application and configure the thread appropriatly.
  87
  88   - "object", G_TYPE, GstTask/GThread
  89       A GstTask/GThread controlling this streaming thread. This can be NULL when
  90       the object controlling the streaming thread is not yet created.
  91
  92   - "flow-return", GstFlowReturn
  93       A status code for why the thread state changed. when threads are created
  94       and started, this is usually GST_FLOW_OK but when they are stopping it
  95       contains the reason code why it stopped.
  96
  97   - "reason", G_TYPE_STRING
  98       A string describing the reason why the thread started/stopped/paused.
  99       Can be NULL if no reason is given.
 100
 101
 102
 103 Events
 104 ~~~~~~
 105
 106
 107
 108
 109