Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Task
is used by Element
and Pad
to provide the data passing
threads in a Pipeline
.
A Pad
will typically start a Task
to push or pull data to/from the
peer pads. Most source elements start a Task
to push data. In some cases
a demuxer element can start a 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 Pad
to start/pause/stop tasks, it
might sometimes be needed to create a Task
manually if it is not related to
a Pad
.
Before the Task
can be run, it needs a RecMutex
that can be set with
taskSetLock
.
The task can be started, paused and stopped with taskStart
, taskPause
and taskStop
respectively or with the taskSetState
function.
A Task
will repeatedly call the TaskFunction
with the user data
that was provided when creating the task with taskNew
. 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 taskStop
will not immediately make sure the task is
not running anymore. Use taskJoin
to make sure the task is completely
stopped and the thread is stopped.
After creating a Task
, use objectUnref
to free its resources. This can
only be done when the task is not running anymore.
Task functions can send a Message
to send out-of-band data to the
application. The application can receive messages from the 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.
Synopsis
- newtype Task = Task (ManagedPtr Task)
- class (GObject o, IsDescendantOf Task o) => IsTask o
- toTask :: (MonadIO m, IsTask o) => o -> m Task
- taskCleanupAll :: (HasCallStack, MonadIO m) => m ()
- taskGetPool :: (HasCallStack, MonadIO m, IsTask a) => a -> m TaskPool
- taskGetState :: (HasCallStack, MonadIO m, IsTask a) => a -> m TaskState
- taskJoin :: (HasCallStack, MonadIO m, IsTask a) => a -> m Bool
- taskNew :: (HasCallStack, MonadIO m) => TaskFunction -> m Task
- taskPause :: (HasCallStack, MonadIO m, IsTask a) => a -> m Bool
- taskResume :: (HasCallStack, MonadIO m, IsTask a) => a -> m Bool
- taskSetEnterCallback :: (HasCallStack, MonadIO m, IsTask a) => a -> TaskThreadFunc -> m ()
- taskSetLeaveCallback :: (HasCallStack, MonadIO m, IsTask a) => a -> TaskThreadFunc -> m ()
- taskSetLock :: (HasCallStack, MonadIO m, IsTask a) => a -> RecMutex -> m ()
- taskSetPool :: (HasCallStack, MonadIO m, IsTask a, IsTaskPool b) => a -> b -> m ()
- taskSetState :: (HasCallStack, MonadIO m, IsTask a) => a -> TaskState -> m Bool
- taskStart :: (HasCallStack, MonadIO m, IsTask a) => a -> m Bool
- taskStop :: (HasCallStack, MonadIO m, IsTask a) => a -> m Bool
Exported types
Memory-managed wrapper type.
Instances
Eq Task Source # | |
GObject Task Source # | |
Defined in GI.Gst.Objects.Task | |
ManagedPtrNewtype Task Source # | |
Defined in GI.Gst.Objects.Task toManagedPtr :: Task -> ManagedPtr Task | |
TypedObject Task Source # | |
Defined in GI.Gst.Objects.Task | |
HasParentTypes Task Source # | |
Defined in GI.Gst.Objects.Task | |
IsGValue (Maybe Task) Source # | Convert |
Defined in GI.Gst.Objects.Task gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Task -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Task) | |
type ParentTypes Task Source # | |
Defined in GI.Gst.Objects.Task |
class (GObject o, IsDescendantOf Task o) => IsTask o Source #
Instances
(GObject o, IsDescendantOf Task o) => IsTask o Source # | |
Defined in GI.Gst.Objects.Task |
Methods
Click to display all available methods, including inherited ones
Methods
addControlBinding, bindProperty, bindPropertyFull, defaultError, forceFloating, freezeNotify, getv, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, isFloating, join, notify, notifyByPspec, pause, ref, refSink, removeControlBinding, resume, runDispose, start, stealData, stealQdata, stop, suggestNextSync, syncValues, thawNotify, unparent, unref, watchClosure.
Getters
getControlBinding, getControlRate, getData, getGValueArray, getName, getParent, getPathString, getPool, getProperty, getQdata, getState, getValue.
Setters
setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setData, setDataFull, setEnterCallback, setLeaveCallback, setLock, setName, setParent, setPool, setProperty, setState.
cleanupAll
taskCleanupAll :: (HasCallStack, MonadIO m) => m () 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.
getPool
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> m TaskPool | Returns: the |
Get the TaskPool
that this task will use for its streaming
threads.
MT safe.
getState
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> m TaskState | Returns: The MT safe. |
Get the current state of the task.
join
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
Joins task
. After this call, it is safe to unref the task
and clean up the lock set with taskSetLock
.
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.
new
:: (HasCallStack, MonadIO m) | |
=> TaskFunction |
|
-> m Task | Returns: A new MT safe. |
Create a new Task that will repeatedly call the provided func
with userData
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 Task
to change the function.
This function will not yet create and start a thread. Use taskStart
or
taskPause
to create and start the GThread.
Before the task can be used, a RecMutex
must be configured using the
taskSetLock
function. This lock will always be acquired while
func
is called.
pause
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
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.
resume
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
Resume task
in case it was paused. If the task was stopped, it will
remain in that state and this function will return False
.
Since: 1.18
setEnterCallback
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> TaskThreadFunc |
|
-> m () |
Call enterFunc
when the task function of task
is entered. userData
will
be passed to enterFunc
and notify
will be called when userData
is no
longer referenced.
setLeaveCallback
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> TaskThreadFunc |
|
-> m () |
Call leaveFunc
when the task function of task
is left. userData
will
be passed to leaveFunc
and notify
will be called when userData
is no
longer referenced.
setLock
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> RecMutex |
|
-> m () |
Set the mutex used by the task. The mutex will be acquired before
calling the TaskFunction
.
This function has to be called before calling taskPause
or
taskStart
.
MT safe.
setPool
:: (HasCallStack, MonadIO m, IsTask a, IsTaskPool b) | |
=> a |
|
-> b |
|
-> m () |
Set pool
as the new GstTaskPool for task
. Any new streaming threads that
will be created by task
will now use pool
.
MT safe.
setState
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> TaskState |
|
-> m Bool | Returns: |
Sets the state of task
to state
.
The task
must have a lock associated with it using
taskSetLock
when going to GST_TASK_STARTED or GST_TASK_PAUSED or
this function will return False
.
MT safe.
start
:: (HasCallStack, MonadIO m, IsTask a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
Starts task
. The task
must have a lock associated with it using
taskSetLock
or this function will return False
.