Top |
Functions
void | (*GstTaskFunction) () |
#define | GST_TASK_BROADCAST() |
#define | GST_TASK_GET_COND() |
#define | GST_TASK_GET_LOCK() |
#define | GST_TASK_SIGNAL() |
#define | GST_TASK_STATE() |
#define | GST_TASK_WAIT() |
GstTask * | gst_task_new () |
void | gst_task_set_lock () |
void | gst_task_set_pool () |
GstTaskPool * | gst_task_get_pool () |
void | (*GstTaskThreadFunc) () |
void | gst_task_set_enter_callback () |
void | gst_task_set_leave_callback () |
GstTaskState | gst_task_get_state () |
gboolean | gst_task_set_state () |
gboolean | gst_task_pause () |
gboolean | gst_task_start () |
gboolean | gst_task_stop () |
gboolean | gst_task_join () |
void | gst_task_cleanup_all () |
Description
GstTask is used by GstElement and GstPad to provide the data passing threads in a GstPipeline.
A GstPad will typically start a GstTask to push or pull data to/from the peer pads. Most source elements start a GstTask to push data. In some cases a demuxer element can start a GstTask to pull data from a peer element. This is typically done when the demuxer can perform random access on the upstream peer element for improved performance.
Although convenience functions exist on GstPad to start/pause/stop tasks, it might sometimes be needed to create a GstTask manually if it is not related to a GstPad.
Before the GstTask can be run, it needs a GRecMutex that can be set with
gst_task_set_lock()
.
The task can be started, paused and stopped with gst_task_start()
, gst_task_pause()
and gst_task_stop()
respectively or with the gst_task_set_state()
function.
A GstTask will repeatedly call the GstTaskFunction with the user data
that was provided when creating the task with gst_task_new()
. While calling
the function it will acquire the provided lock. The provided lock is released
when the task pauses or stops.
Stopping a task with gst_task_stop()
will not immediately make sure the task is
not running anymore. Use gst_task_join()
to make sure the task is completely
stopped and the thread is stopped.
After creating a GstTask, use gst_object_unref()
to free its resources. This can
only be done when the task is not running anymore.
Task functions can send a GstMessage to send out-of-band data to the application. The application can receive messages from the GstBus in its mainloop.
For debugging purposes, the task will configure its object name as the thread name on Linux. Please note that the object name should be configured before the task is started; changing the object name after the task has been started, has no effect on the thread name.
Functions
GstTaskFunction ()
void
(*GstTaskFunction) (gpointer user_data
);
A function that will repeatedly be called in the thread created by a GstTask.
GST_TASK_BROADCAST()
#define GST_TASK_BROADCAST(task) g_cond_broadcast(GST_TASK_GET_COND (task))
Send a broadcast signal to all waiting task conds
GST_TASK_GET_COND()
#define GST_TASK_GET_COND(task) (&GST_TASK_CAST(task)->cond)
Get access to the cond of the task.
GST_TASK_GET_LOCK()
#define GST_TASK_GET_LOCK(task) (GST_TASK_CAST(task)->lock)
Get access to the task lock.
GST_TASK_SIGNAL()
#define GST_TASK_SIGNAL(task) g_cond_signal(GST_TASK_GET_COND (task))
Signal the task cond
GST_TASK_STATE()
#define GST_TASK_STATE(task) (GST_TASK_CAST(task)->state)
Get access to the state of the task.
GST_TASK_WAIT()
#define GST_TASK_WAIT(task) g_cond_wait(GST_TASK_GET_COND (task), GST_OBJECT_GET_LOCK (task))
Wait for the task cond to be signalled
gst_task_new ()
GstTask * gst_task_new (GstTaskFunction func
,gpointer user_data
,GDestroyNotify notify
);
Create a new Task that will repeatedly call the provided func
with user_data
as a parameter. Typically the task will run in
a new thread.
The function cannot be changed after the task has been created. You must create a new GstTask to change the function.
This function will not yet create and start a thread. Use gst_task_start()
or
gst_task_pause()
to create and start the GThread.
Before the task can be used, a GRecMutex must be configured using the
gst_task_set_lock()
function. This lock will always be acquired while
func
is called.
Parameters
func |
The GstTaskFunction to use |
|
user_data |
User data to pass to |
|
notify |
the function to call when |
gst_task_set_lock ()
void gst_task_set_lock (GstTask *task
,GRecMutex *mutex
);
Set the mutex used by the task. The mutex will be acquired before calling the GstTaskFunction.
This function has to be called before calling gst_task_pause()
or
gst_task_start()
.
MT safe.
gst_task_set_pool ()
void gst_task_set_pool (GstTask *task
,GstTaskPool *pool
);
Set pool
as the new GstTaskPool for task
. Any new streaming threads that
will be created by task
will now use pool
.
MT safe.
gst_task_get_pool ()
GstTaskPool *
gst_task_get_pool (GstTask *task
);
Get the GstTaskPool that this task will use for its streaming threads.
MT safe.
GstTaskThreadFunc ()
void (*GstTaskThreadFunc) (GstTask *task
,GThread *thread
,gpointer user_data
);
Custom GstTask thread callback functions that can be installed.
gst_task_set_enter_callback ()
void gst_task_set_enter_callback (GstTask *task
,GstTaskThreadFunc enter_func
,gpointer user_data
,GDestroyNotify notify
);
Call enter_func
when the task function of task
is entered. user_data
will
be passed to enter_func
and notify
will be called when user_data
is no
longer referenced.
Parameters
task |
The GstTask to use |
|
enter_func |
[in] | |
user_data |
user data passed to |
|
notify |
called when |
gst_task_set_leave_callback ()
void gst_task_set_leave_callback (GstTask *task
,GstTaskThreadFunc leave_func
,gpointer user_data
,GDestroyNotify notify
);
Call leave_func
when the task function of task
is left. user_data
will
be passed to leave_func
and notify
will be called when user_data
is no
longer referenced.
Parameters
task |
The GstTask to use |
|
leave_func |
[in] | |
user_data |
user data passed to |
|
notify |
called when |
gst_task_get_state ()
GstTaskState
gst_task_get_state (GstTask *task
);
Get the current state of the task.
gst_task_set_state ()
gboolean gst_task_set_state (GstTask *task
,GstTaskState state
);
Sets the state of task
to state
.
The task
must have a lock associated with it using
gst_task_set_lock()
when going to GST_TASK_STARTED or GST_TASK_PAUSED or
this function will return FALSE
.
MT safe.
gst_task_pause ()
gboolean
gst_task_pause (GstTask *task
);
Pauses task
. This method can also be called on a task in the
stopped state, in which case a thread will be started and will remain
in the paused state. This function does not wait for the task to complete
the paused state.
gst_task_start ()
gboolean
gst_task_start (GstTask *task
);
Starts task
. The task
must have a lock associated with it using
gst_task_set_lock()
or this function will return FALSE
.
gst_task_stop ()
gboolean
gst_task_stop (GstTask *task
);
Stops task
. This method merely schedules the task to stop and
will not wait for the task to have completely stopped. Use
gst_task_join()
to stop and wait for completion.
gst_task_join ()
gboolean
gst_task_join (GstTask *task
);
Joins task
. After this call, it is safe to unref the task
and clean up the lock set with gst_task_set_lock()
.
The task will automatically be stopped with this call.
This function cannot be called from within a task function as this would cause a deadlock. The function will detect this and print a g_warning.
Types and Values
struct GstTask
struct GstTask { GstTaskState state; GCond cond; GRecMutex *lock; GstTaskFunction func; gpointer user_data; GDestroyNotify notify; gboolean running; };
The GstTask object.
Members
GstTaskState |
the state of the task |
|
GCond |
used to pause/resume the task |
|
GRecMutex * |
The lock taken when iterating the task function |
|
GstTaskFunction |
the function executed by this task |
|
gpointer |
user_data passed to the task function |
|
GDestroyNotify |
GDestroyNotify for |
|
gboolean |
a flag indicating that the task is running |