From: Wim Taymans <wim.taymans@gmail.com>
Date: Thu, 20 Oct 2005 19:30:57 +0000 (+0000)
Subject: gst/gsttask.*: More docs.
X-Git-Tag: RELEASE-0_9_4~14
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9e28a129a5d2b435516942ea3e4b71283b7a9edd;p=platform%2Fupstream%2Fgstreamer.git

gst/gsttask.*: More docs.

Original commit message from CVS:
* gst/gsttask.c:
* gst/gsttask.h:
More docs.
---

diff --git a/ChangeLog b/ChangeLog
index 6699940..fe336ac 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 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),
diff --git a/gst/gsttask.c b/gst/gsttask.c
index a112054..29ed4e7 100644
--- a/gst/gsttask.c
+++ b/gst/gsttask.c
@@ -20,6 +20,42 @@
  * 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"
diff --git a/gst/gsttask.h b/gst/gsttask.h
index 33c26b0..5968ea0 100644
--- a/gst/gsttask.h
+++ b/gst/gsttask.h
@@ -41,12 +41,26 @@ typedef void         (*GstTaskFunction)          (void *data);
 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)
@@ -56,6 +70,17 @@ typedef enum {
 
 #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;