GstTask

GstTask — Abstraction of GStreamer streaming threads.

Synopsis


#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)
void                gst_task_cleanup_all                (void);
GstTask*            gst_task_create                     (GstTaskFunction func,
                                                         gpointer data);
GstTaskState        gst_task_get_state                  (GstTask *task);
gboolean            gst_task_join                       (GstTask *task);
gboolean            gst_task_pause                      (GstTask *task);
void                gst_task_set_lock                   (GstTask *task,
                                                         GStaticRecMutex *mutex);
gboolean            gst_task_start                      (GstTask *task);
gboolean            gst_task_stop                       (GstTask *task);


Object Hierarchy


  GObject
   +----GstObject
         +----GstTask

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 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.

A GstTask will repeadedly call the GstTaskFunction with the user data that was provided when creating the task with gst_task_create(). Before calling the function it will acquire the provided lock.

Stopping a task with gst_task_stop() will not immediatly 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.

Last reviewed on 2006-02-13 (0.10.4)

Details

GstTask

typedef struct {
  GstTaskState     state;
  GCond 	  *cond;

  GStaticRecMutex *lock;

  GstTaskFunction  func;
  gpointer 	   data;

  gboolean	   running;
} GstTask;

The GstTask object.

GstTaskState state; the state of the task
GCond *cond; used to pause/resume the task
GStaticRecMutex *lock; The lock taken when iterating the taskfunction
GstTaskFunction func; the function executed by this task
gpointer data; data passed to the task function
gboolean running; a flag indicating that the task is running.
gpointer _gst_reserved[GST_PADDING + 0];

GstTaskFunction ()

void                (*GstTaskFunction)                  (void *data);

A function that will repeadedly be called in the thread created by a GstTask.

data : user data passed to the function

enum GstTaskState

typedef enum {
  GST_TASK_STARTED,
  GST_TASK_STOPPED,
  GST_TASK_PAUSED
} GstTaskState;

The different states a task can be in

GST_TASK_STARTED the task is started and running
GST_TASK_STOPPED the task is stopped
GST_TASK_PAUSED the task is paused

GST_TASK_BROADCAST()

#define GST_TASK_BROADCAST(task)	g_cond_breadcast(GST_TASK_GET_COND (task))

Send a broadcast signal to all waiting task conds

task : Task to broadcast

GST_TASK_GET_COND()

#define GST_TASK_GET_COND(task)		(GST_TASK_CAST(task)->cond)

Get access to the cond of the task.

task : Task to get the cond of

GST_TASK_GET_LOCK()

#define GST_TASK_GET_LOCK(task)		(GST_TASK_CAST(task)->lock)

Get access to the task lock.

task : Task to get the lock of

GST_TASK_SIGNAL()

#define GST_TASK_SIGNAL(task)		g_cond_signal(GST_TASK_GET_COND (task))

Signal the task cond

task : Task to signal

GST_TASK_STATE()

#define GST_TASK_STATE(task)		(GST_TASK_CAST(task)->state)

Get access to the state of the task.

task : Task to get the state of

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

task : Task to wait for

gst_task_cleanup_all ()

void                gst_task_cleanup_all                (void);

Wait for all tasks to be stopped. This is mainly used internally to ensure proper cleanup of internal datastructures in testsuites.

MT safe.


gst_task_create ()

GstTask*            gst_task_create                     (GstTaskFunction func,
                                                         gpointer data);

Create a new Task that will repeadedly 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.

func : The GstTaskFunction to use
data : User data to pass to func
Returns : A new GstTask. MT safe.

gst_task_get_state ()

GstTaskState        gst_task_get_state                  (GstTask *task);

Get the current state of the task.

task : The GstTask to query
Returns : The GstTaskState of the task MT safe.

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.

task : The GstTask to join
Returns : TRUE if the task could be joined. 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.

task : The GstTask to pause
Returns : TRUE if the task could be paused. MT safe.

gst_task_set_lock ()

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.

task : The GstTask to use
mutex : The GMutex to use

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 thsi function will return FALSE.

task : The GstTask to start
Returns : TRUE if the task could be started. MT safe.

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.

task : The GstTask to stop
Returns : TRUE if the task could be stopped. MT safe.

See Also

GstElement, GstPad