GstTask

## GstTask GstTask — Abstraction of GStreamer streaming threads. |

## Synopsis

    #include <gst/gst.h>

    struct              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_new                        (GstTaskFunction func,
                                                             gpointer data);
    void                gst_task_set_lock                   (GstTask *task,
                                                             GRecMutex *mutex);
    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
       +----GInitiallyUnowned
             +----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_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.

Last reviewed on 2012-03-29 (0.11.3)

## Details

### struct GstTask

    struct GstTask {
      GstTaskState     state;
      GCond            cond;

      GRecMutex       *lock;

      GstTaskFunction  func;
      gpointer         data;

      gboolean         running;
    };

The GstTask object.

GstTaskState `state`; | the state of the task
GCond `cond`; | used to pause/resume the task
GRecMutex *`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

### 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_broadcast(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_new ()

    GstTask *           gst_task_new                        (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`. [closure]
Returns : | A new GstTask. MT safe. [transfer full]

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

`task` : | The GstTask to use
`mutex` : | The GRecMutex to use

### 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. [transfer none]

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. [transfer full]

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. [in]
`user_data` : | user data passed to the callbacks. [closure]
`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