Gst.Task¶

Subclasses:: None

Methods¶

Inherited:: Gst.Object (27), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`cleanup_all` ()
class	`new` (func, *user_data)
	`get_pool` ()
	`get_state` ()
	`join` ()
	`pause` ()
	`resume` ()
	`set_enter_callback` (enter_func, *user_data)
	`set_leave_callback` (leave_func, *user_data)
	`set_lock` (mutex)
	`set_pool` (pool)
	`set_state` (state)
	`start` ()
	`stop` ()

Virtual Methods¶

Inherited:: Gst.Object (1), GObject.Object (7)

Properties¶

Inherited:: Gst.Object (2)

Signals¶

Inherited:: Gst.Object (1), GObject.Object (1)

Fields¶

Inherited:: Gst.Object (1), GObject.Object (1)

Name	Type	Access	Description
cond	`GLib.Cond`	r	used to pause/resume the task
func	`Gst.TaskFunction`	r	the function executed by this task
lock	`GLib.RecMutex`	r	The lock taken when iterating the task function
notify	`GLib.DestroyNotify`	r	`GLib.DestroyNotify` for user_data
object	`Gst.Object`	r
running	`bool`	r	a flag indicating that the task is running
state	`Gst.TaskState`	r	the state of the task
thread	`GLib.Thread`	r
user_data	`object`	r	user_data passed to the task function

Class Details¶

class Gst.Task(**kwargs)¶

Bases:: Gst.Object
Abstract:: No
Structure:: Gst.TaskClass

Gst.Task is used by Gst.Element and Gst.Pad to provide the data passing threads in a Gst.Pipeline.

A Gst.Pad will typically start a Gst.Task to push or pull data to/from the peer pads. Most source elements start a Gst.Task to push data. In some cases a demuxer element can start a Gst.Task 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 Gst.Pad to start/pause/stop tasks, it might sometimes be needed to create a Gst.Task manually if it is not related to a Gst.Pad.

Before the Gst.Task can be run, it needs a GLib.RecMutex 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 Gst.Task will repeatedly call the Gst.TaskFunction 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 Gst.Task, 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 Gst.Message to send out-of-band data to the application. The application can receive messages from the Gst.Bus 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.

classmethod cleanup_all()[source]¶

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.

classmethod new(func, *user_data)[source]¶

Parameters:

func (Gst.TaskFunction) – The Gst.TaskFunction to use
user_data (object or None) – User data to pass to func

Returns:

A new Gst.Task.

MT safe.

Return type:

Gst.Task

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 Gst.Task 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 GLib.Thread.

Before the task can be used, a GLib.RecMutex must be configured using the Gst.Task.set_lock() function. This lock will always be acquired while func is called.

get_pool()[source]¶

Returns:: the Gst.TaskPool used by self. Gst.Object.unref() after usage.
Return type:: Gst.TaskPool

Get the Gst.TaskPool that this task will use for its streaming threads.

MT safe.

get_state()[source]¶

Returns:

The Gst.TaskState of the task

MT safe.

Return type:

Gst.TaskState

Get the current state of the task.

join()[source]¶

Returns:

True if the task could be joined.

MT safe.

Return type:

bool

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

pause()[source]¶

Returns:

True if the task could be paused.

MT safe.

Return type:

bool

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

resume()[source]¶

Returns:

True if the task could be resumed.

MT safe.

Return type:

bool

Resume self in case it was paused. If the task was stopped, it will remain in that state and this function will return False.

New in version 1.18.

set_enter_callback(enter_func, *user_data)[source]¶

Parameters:

enter_func (Gst.TaskThreadFunc) – a Gst.TaskThreadFunc
user_data (object or None) – user data passed to enter_func

Call enter_func when the task function of self is entered. user_data will be passed to enter_func and notify will be called when user_data is no longer referenced.

set_leave_callback(leave_func, *user_data)[source]¶

Parameters:

leave_func (Gst.TaskThreadFunc) – a Gst.TaskThreadFunc
user_data (object or None) – user data passed to leave_func

Call leave_func when the task function of self is left. user_data will be passed to leave_func and notify will be called when user_data is no longer referenced.

set_lock(mutex)[source]¶

Parameters:: mutex (GLib.RecMutex) – The GLib.RecMutex to use

Set the mutex used by the task. The mutex will be acquired before calling the Gst.TaskFunction.

This function has to be called before calling Gst.Task.pause() or Gst.Task.start().

MT safe.

set_pool(pool)[source]¶

Parameters:: pool (Gst.TaskPool) – a Gst.TaskPool

Set pool as the new Gst.TaskPool for self. Any new streaming threads that will be created by self will now use pool.

MT safe.

set_state(state)[source]¶

Parameters:: state (Gst.TaskState) – the new task state
Returns:: True if the state could be changed.
Return type:: bool

Sets the state of self to state.

The self must have a lock associated with it using Gst.Task.set_lock() when going to Gst.TaskState.STARTED or Gst.TaskState.PAUSED or this function will return False.

MT safe.

start()[source]¶

Returns:

True if the task could be started.

MT safe.

Return type:

bool

Starts self. The self must have a lock associated with it using Gst.Task.set_lock() or this function will return False.

stop()[source]¶

Returns:

True if the task could be stopped.

MT safe.

Return type:

bool

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