2005-10-20 Wim Taymans <wim@fluendo.com>
+ * gst/gsttask.c:
+ * gst/gsttask.h:
+ More docs.
+
+2005-10-20 Wim Taymans <wim@fluendo.com>
+
* gst/gstbin.c: (message_check), (bin_replace_message),
(bin_remove_messages), (is_eos), (gst_bin_add_func),
(update_degree), (gst_bin_sort_iterator_next),
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gsttask
+ * @short_description: Abstraction of GStreamer streaming threads.
+ * @see_also: #GstElement, #GstPad
+ *
+ * GstTasks are used by GstElements and GstPads to provide the data passing
+ * threads in a pipeline.
+ *
+ * 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 provided 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 anymnore. 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.
+ */
+
#include "gst_private.h"
#include "gstinfo.h"
typedef struct _GstTask GstTask;
typedef struct _GstTaskClass GstTaskClass;
+/**
+ * GstTaskState:
+ * @GST_TASK_STARTED: the task is started and running
+ * @GST_TASK_STOPPED: the task is stopped
+ * @GST_TASK_PAUSED: the task is paused
+ *
+ * The different states a task can be in
+ */
typedef enum {
GST_TASK_STARTED,
GST_TASK_STOPPED,
GST_TASK_PAUSED,
} GstTaskState;
+/**
+ * GST_TASK_STATE:
+ * @task: Task to get the state of
+ *
+ * Get access to the state of the task.
+ */
#define GST_TASK_STATE(task) (GST_TASK_CAST(task)->state)
#define GST_TASK_GET_COND(task) (GST_TASK_CAST(task)->cond)
#define GST_TASK_GET_LOCK(task) (GST_TASK_CAST(task)->lock)
+/**
+ * GstTask:
+ * @state: the state of the task
+ * @cond: used to pause/resume the task
+ * @lock: The lock taken when iterating the taskfunction
+ * @func: the function executed by this task
+ * @data: data passed to the task function
+ * @running: a flag indicating that the task is running.
+ *
+ * The GstTask object.
+ */
struct _GstTask {
GstObject object;