| GStreamer 0.10 Core Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
#include <gst/gst.h>
GstTask;
void (*GstTaskFunction) (void *data);
enum GstTaskState;
#define GST_TASK_BROADCAST (task)
#define GST_TASK_GET_COND (task)
#define GST_TASK_GET_LOCK (task)
#define GST_TASK_SIGNAL (task)
#define GST_TASK_STATE (task)
#define GST_TASK_WAIT (task)
GstTask* gst_task_create (GstTaskFunction func,
gpointer data);
void gst_task_set_lock (GstTask *task,
GStaticRecMutex *mutex);
void gst_task_set_priority (GstTask *task,
GThreadPriority priority);
void gst_task_set_pool (GstTask *task,
GstTaskPool *pool);
GstTaskPool * gst_task_get_pool (GstTask *task);
GstTaskThreadCallbacks;
void gst_task_set_thread_callbacks (GstTask *task,
GstTaskThreadCallbacks *callbacks,
gpointer user_data,
GDestroyNotify notify);
GstTaskState gst_task_get_state (GstTask *task);
gboolean gst_task_set_state (GstTask *task,
GstTaskState state);
gboolean gst_task_pause (GstTask *task);
gboolean gst_task_start (GstTask *task);
gboolean gst_task_stop (GstTask *task);
gboolean gst_task_join (GstTask *task);
void gst_task_cleanup_all (void);
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 GStaticRecMutex 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_create(). 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 it 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.
Last reviewed on 2006-02-13 (0.10.4)
typedef struct {
GstTaskState state;
GCond *cond;
GStaticRecMutex *lock;
GstTaskFunction func;
gpointer data;
gboolean running;
} GstTask;
The GstTask object.
GstTaskState |
the state of the task |
GCond * |
used to pause/resume the task |
GStaticRecMutex * |
The lock taken when iterating the task function |
GstTaskFunction |
the function executed by this task |
gpointer |
data passed to the task function |
gboolean |
a flag indicating that the task is running |
gpointer |
void (*GstTaskFunction) (void *data);
A function that will repeatedly be called in the thread created by a GstTask.
|
user data passed to the function |
typedef enum {
GST_TASK_STARTED,
GST_TASK_STOPPED,
GST_TASK_PAUSED
} GstTaskState;
The different states a task can be in
#define GST_TASK_BROADCAST(task) g_cond_breadcast(GST_TASK_GET_COND (task))
Send a broadcast signal to all waiting task conds
|
Task to broadcast |
#define GST_TASK_GET_COND(task) (GST_TASK_CAST(task)->cond)
Get access to the cond of the task.
|
Task to get the cond of |
#define GST_TASK_GET_LOCK(task) (GST_TASK_CAST(task)->lock)
Get access to the task lock.
|
Task to get the lock of |
#define GST_TASK_SIGNAL(task) g_cond_signal(GST_TASK_GET_COND (task))
Signal the task cond
|
Task to signal |
#define GST_TASK_STATE(task) (GST_TASK_CAST(task)->state)
Get access to the state of the task.
|
Task to get the state of |
#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
|
Task to wait for |
GstTask* gst_task_create (GstTaskFunction func, gpointer data);
Create a new Task that will repeatedly call the provided func
with 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 GStaticRecMutex must be configured using the
gst_task_set_lock() function. This lock will always be acquired while
func is called.
|
The GstTaskFunction to use |
|
User data to pass to func
|
Returns : |
A new GstTask. MT safe. |
void gst_task_set_lock (GstTask *task, GStaticRecMutex *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.
void gst_task_set_priority (GstTask *task, GThreadPriority priority);
Changes the priority of task to priority.
Note: try not to depend on task priorities.
MT safe.
|
a GstTask |
|
a new priority for task
|
Since 0.10.24
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.
|
a GstTask |
|
a GstTaskPool |
Since 0.10.24
GstTaskPool * gst_task_get_pool (GstTask *task);
Get the GstTaskPool that this task will use for its streaming threads.
MT safe.
|
a GstTask |
Returns : |
the GstTaskPool used by task. gst_object_unref()
after usage.
|
Since 0.10.24
typedef struct {
/* manage the lifetime of the thread */
void (*enter_thread) (GstTask *task, GThread *thread, gpointer user_data);
void (*leave_thread) (GstTask *task, GThread *thread, gpointer user_data);
} GstTaskThreadCallbacks;
Custom GstTask thread callback functions that can be installed.
| a thread is entered, this callback is called when the new thread enters its function. | |
| a thread is exiting, this is called when the thread is about to leave its function |
Since 0.10.24
void gst_task_set_thread_callbacks (GstTask *task, GstTaskThreadCallbacks *callbacks, gpointer user_data, GDestroyNotify notify);
Set callbacks which will be executed when a new thread is needed, the thread function is entered and left and when the thread is joined.
By default a thread for task will be created from a default thread pool.
Objects can use custom GThreads or can perform additional configuration of the threads (such as changing the thread priority) by installing callbacks.
MT safe.
|
The GstTask to use |
|
a GstTaskThreadCallbacks pointer |
|
user data passed to the callbacks |
|
called when user_data is no longer referenced
|
Since 0.10.24
GstTaskState gst_task_get_state (GstTask *task);
Get the current state of the task.
|
The GstTask to query |
Returns : |
The GstTaskState of the task MT safe. |
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.
Since 0.10.24
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.
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.
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.
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.