## 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)
    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);

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

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 task function
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 - 1]; |

### GstTaskFunction ()

    void                (*GstTaskFunction)                  (void *data);

A function that will repeatedly 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_create ()

    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.

`func` : | The GstTaskFunction to use
`data` : | User data to pass to `func`
Returns : | A new GstTask. 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_set_priority ()

    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.

`task` : | a GstTask
`priority` : | a new priority for `task`

Since 0.10.24

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

`task` : | a GstTask
`pool` : | a GstTaskPool

Since 0.10.24

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

`task` : | a GstTask
Returns : | the GstTaskPool used by `task`. `gst_object_unref()` after usage.

Since 0.10.24

### GstTaskThreadCallbacks

    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.

`enter_thread` () | a thread is entered, this callback is called when the new thread enters its function.
`leave_thread` () | a thread is exiting, this is called when the thread is about to leave its function

Since 0.10.24

### gst_task_set_thread_callbacks ()

    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.

`task` : | The GstTask to use
`callbacks` : | a GstTaskThreadCallbacks pointer
`user_data` : | user data passed to the callbacks
`notify` : | called when `user_data` is no longer referenced

Since 0.10.24

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

`task` : | a GstTask
`state` : | the new task state
Returns : | `TRUE` if the state could be changed.

Since 0.10.24

### 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_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`.

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

### 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_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 data structures in test suites.

MT safe.

## See Also

#GstElement, GstPad