mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-25 15:58:24 +00:00
0b5f070eae
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.
97 lines
3.6 KiB
Plaintext
97 lines
3.6 KiB
Plaintext
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
|
|
------
|
|
|
|
|
|
|
|
|
|
|