asyncworker r87 - in trunk: . docs/reference docs/reference/tmpl include/oasyncworker liboasyncworker samples/printqueue samples/simple samples/treeview

From: pvanhoof svn gnome org
To: svn-commits-list gnome org
Subject: asyncworker r87 - in trunk: . docs/reference docs/reference/tmpl include/oasyncworker liboasyncworker samples/printqueue samples/simple samples/treeview
Date: Sun, 27 Apr 2008 12:41:11 +0100 (BST)
Author: pvanhoof
Date: Sun Apr 27 11:41:10 2008
New Revision: 87
URL: http://svn.gnome.org/viewvc/asyncworker?rev=87&view=rev

Log:
2008-04-27  Philip Van Hoof  <pvanhoof gnome org>

        * Various API changes
        * Fixed the gtk-docs
        * Fixed the samples for the API changes



Modified:
   trunk/ChangeLog
   trunk/docs/reference/Makefile.am
   trunk/docs/reference/tmpl/oasyncworker.sgml
   trunk/docs/reference/tmpl/oasyncworkertask.sgml
   trunk/include/oasyncworker/oasyncworker.h
   trunk/include/oasyncworker/oasyncworkertask.h
   trunk/liboasyncworker/oasyncworker.c
   trunk/liboasyncworker/oasyncworkertask.c
   trunk/samples/printqueue/main.c
   trunk/samples/simple/main.c
   trunk/samples/treeview/main.c

Modified: trunk/docs/reference/Makefile.am
==============================================================================
--- trunk/docs/reference/Makefile.am	(original)
+++ trunk/docs/reference/Makefile.am	Sun Apr 27 11:41:10 2008
@@ -41,9 +41,9 @@
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
 # if $(DOC_MODULE).types is non-empty.
-GTKDOC_CFLAGS =
+GTKDOC_CFLAGS = $(LIBOASYNCWORKER_CFLAGS) -I$(top_srcdir)/include 
 
-GTKDOC_LIBS =
+GTKDOC_LIBS = $(LIBOASYNCWORKER_LIBS) $(top_builddir)/liboasyncworker/liboasyncworker-1.0.la
 
 # Ugly hacks go here
 $(DOC_MODULE)-overrides.txt:

Modified: trunk/docs/reference/tmpl/oasyncworker.sgml
==============================================================================
--- trunk/docs/reference/tmpl/oasyncworker.sgml	(original)
+++ trunk/docs/reference/tmpl/oasyncworker.sgml	Sun Apr 27 11:41:10 2008
@@ -8,7 +8,7 @@
 <para>
 The worker queue is the entity that will process your tasks. It will automatically launch a worker thread and will sort tasks 
 on priorty when a task gets added. It has support for cancellation of tasks. Note that the task that is to be cancelled needs to have
-cancellation points in it's body. The cancellation will then happen at the first next such cancellation point.
+cancellation points in its body. The cancellation will then happen at the first next such cancellation point.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,11 +16,7 @@
 
 </para>
 
-<!-- ##### MACRO O_ASYNC_WORKER_INSIDE_O_ASYNC_WORKER_H ##### -->
-<para>
-
-</para>
-
+<!-- ##### SECTION Stability_Level ##### -->
 
 
 <!-- ##### MACRO O_ASYNC_WORKER_TYPE ##### -->
@@ -60,6 +56,58 @@
 </para>
 
 
+<!-- ##### STRUCT OAsyncWorkerTask ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT OAsyncWorker ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL OAsyncWorker::task-added ##### -->
+<para>
+
+</para>
+
+ oasyncworker: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL OAsyncWorker::task-cancelled ##### -->
+<para>
+
+</para>
+
+ oasyncworker: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL OAsyncWorker::task-finished ##### -->
+<para>
+
+</para>
+
+ oasyncworker: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL OAsyncWorker::task-removed ##### -->
+<para>
+
+</para>
+
+ oasyncworker: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL OAsyncWorker::task-started ##### -->
+<para>
+
+</para>
+
+ oasyncworker: the object which received the signal.
+ arg1: 
+
 <!-- ##### FUNCTION o_async_worker_new ##### -->
 <para>
 
@@ -94,7 +142,6 @@
 </para>
 
 @queue: 
- found: 
 @Returns: 
 
 
@@ -105,7 +152,6 @@
 
 @queue: 
 @task_id: 
- found: 
 @Returns: 
 
 
@@ -165,3 +211,10 @@
 @Returns: 
 
 
+<!-- ##### MACRO O_ASYNC_WORKER_INSIDE_O_ASYNC_WORKER_H ##### -->
+<para>
+
+</para>
+
+
+

Modified: trunk/docs/reference/tmpl/oasyncworkertask.sgml
==============================================================================
--- trunk/docs/reference/tmpl/oasyncworkertask.sgml	(original)
+++ trunk/docs/reference/tmpl/oasyncworkertask.sgml	Sun Apr 27 11:41:10 2008
@@ -19,6 +19,9 @@
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO O_ASYNC_WORKER_TASK_TYPE ##### -->
 <para>
 
@@ -56,6 +59,12 @@
 </para>
 
 
+<!-- ##### STRUCT OAsyncWorkerTask ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### USER_FUNCTION OAsyncWorkerTaskFunc ##### -->
 <para>
 

Modified: trunk/include/oasyncworker/oasyncworker.h
==============================================================================
--- trunk/include/oasyncworker/oasyncworker.h	(original)
+++ trunk/include/oasyncworker/oasyncworker.h	Sun Apr 27 11:41:10 2008
@@ -23,10 +23,6 @@
 #include <glib.h>
 #include <glib-object.h>
 
-#define O_ASYNC_WORKER_INSIDE_O_ASYNC_WORKER_H
-#include <oasyncworker/oasyncworkertask.h>
-#undef O_ASYNC_WORKER_INSIDE_O_ASYNC_WORKER_H
-
 G_BEGIN_DECLS
 
 #define O_ASYNC_WORKER_TYPE		(o_async_worker_get_type ())
@@ -37,8 +33,10 @@
 #define O_ASYNC_WORKER_GET_CLASS(obj)	(G_TYPE_INSTANCE_GET_CLASS ((obj), O_ASYNC_WORKER_TYPE, OAsyncWorkerClass))
 
 typedef struct _OAsyncWorker OAsyncWorker;
-typedef struct _OAsyncWorkerPrivate OAsyncWorkerPrivate;
 typedef struct _OAsyncWorkerClass OAsyncWorkerClass;
+typedef struct _OAsyncWorkerPrivate OAsyncWorkerPrivate;
+
+typedef struct _OAsyncWorkerTask OAsyncWorkerTask;
 
 struct _OAsyncWorker
 {
@@ -57,13 +55,15 @@
 	void			(*task_cancelled)		(gpointer instance, gint arg1);
 };
 
+
+
 GType			o_async_worker_get_type        		(void);
 OAsyncWorker*		o_async_worker_new              	(void);
 
 gint			o_async_worker_add			(OAsyncWorker *queue, OAsyncWorkerTask *task);
 void			o_async_worker_remove			(OAsyncWorker *queue, gint task_id, gboolean run_callback);
-OAsyncWorkerTask	o_async_worker_get_current		(OAsyncWorker *queue, gboolean *found);
-OAsyncWorkerTask	o_async_worker_get_with_id		(OAsyncWorker *queue, gint task_id, gboolean *found);
+OAsyncWorkerTask*	o_async_worker_get_current		(OAsyncWorker *queue);
+OAsyncWorkerTask*	o_async_worker_get_with_id		(OAsyncWorker *queue, gint task_id);
 gint			o_async_worker_add_wait			(OAsyncWorker *queue, gint micros, gint priority);
 void			o_async_worker_join			(OAsyncWorker *queue);
 
@@ -75,4 +75,8 @@
 
 G_END_DECLS
 
+#define O_ASYNC_WORKER_INSIDE_O_ASYNC_WORKER_H
+#include <oasyncworker/oasyncworkertask.h>
+#undef O_ASYNC_WORKER_INSIDE_O_ASYNC_WORKER_H
+
 #endif

Modified: trunk/include/oasyncworker/oasyncworkertask.h
==============================================================================
--- trunk/include/oasyncworker/oasyncworkertask.h	(original)
+++ trunk/include/oasyncworker/oasyncworkertask.h	Sun Apr 27 11:41:10 2008
@@ -26,6 +26,8 @@
 #include <glib.h>
 #include <glib-object.h>
 
+#include <oasyncworker/oasyncworker.h>
+
 G_BEGIN_DECLS
 
 #define O_ASYNC_WORKER_TASK_TYPE			(o_async_worker_task_get_type ())
@@ -35,7 +37,6 @@
 #define G_IS_THREAD_QUEUE_TASK_CLASS(klass)		(G_TYPE_CHECK_CLASS_TYPE ((klass), O_ASYNC_WORKER_TASK_TYPE))
 #define O_ASYNC_WORKER_TASK_GET_CLASS(obj)		(G_TYPE_INSTANCE_GET_CLASS ((obj), O_ASYNC_WORKER_TASK_TYPE, OAsyncWorkerTaskClass))
 
-typedef struct _OAsyncWorkerTask OAsyncWorkerTask;
 typedef struct _OAsyncWorkerTaskPrivate OAsyncWorkerTaskPrivate;
 typedef struct _OAsyncWorkerTaskClass OAsyncWorkerTaskClass;
 
@@ -69,7 +70,7 @@
 
 gboolean			o_async_worker_task_is_cancelled	(OAsyncWorkerTask *task);
 
-gpointer			o_async_worker_task_get_queue		(OAsyncWorkerTask *task);
+OAsyncWorker*			o_async_worker_task_get_queue		(OAsyncWorkerTask *task);
 
 
 void				o_async_worker_task_cancel_point	(OAsyncWorkerTask *task, gboolean run_callback);

Modified: trunk/liboasyncworker/oasyncworker.c
==============================================================================
--- trunk/liboasyncworker/oasyncworker.c	(original)
+++ trunk/liboasyncworker/oasyncworker.c	Sun Apr 27 11:41:10 2008
@@ -163,7 +163,7 @@
 
 /**
  * OAsyncWorker::task-started
- * @self: the object on which the signal is emitted
+ * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got started
  * @user_data: user data set when the signal handler was connected.
  *
@@ -171,6 +171,9 @@
  *
  * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
  * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
+ * Read http://live.gnome.org/GdkLock for more information.
+ *
+ * Since: 1.0
  **/
 	queue_signals[TASK_STARTED] =
 		g_signal_new ("task_started",
@@ -184,7 +187,7 @@
 
 /**
  * OAsyncWorker::task-cancelled
- * @self: the object on which the signal is emitted
+ * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got cancelled
  * @user_data: user data set when the signal handler was connected.
  *
@@ -192,6 +195,9 @@
  *
  * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
  * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
+ * Read http://live.gnome.org/GdkLock for more information.
+ *
+ * Since: 1.0
  **/
 	queue_signals[TASK_CANCELLED] =
 		g_signal_new ("task_cancelled",
@@ -205,7 +211,7 @@
 
 /**
  * OAsyncWorker::task-added
- * @self: the object on which the signal is emitted
+ * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got added
  * @user_data: user data set when the signal handler was connected.
  *
@@ -213,6 +219,10 @@
  *
  * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
  * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
+ * They are thrown to the #GMainLoop, however. Read http://live.gnome.org/GdkLock 
+ * for more information.
+ *
+ * Since: 1.0
  **/
 	queue_signals[TASK_ADDED] =
 		g_signal_new ("task_added",
@@ -227,7 +237,7 @@
 
 /**
  * OAsyncWorker::task-finished
- * @self: the object on which the signal is emitted
+ * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got started
  * @user_data: user data set when the signal handler was connected.
  *
@@ -235,6 +245,10 @@
  *
  * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
  * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
+ * They are thrown to the #GMainLoop, however. Read http://live.gnome.org/GdkLock
+ * for more information.
+ *
+ * Since: 1.0
  **/
 	queue_signals[TASK_FINISHED] =
 		g_signal_new ("task_finished",
@@ -256,6 +270,10 @@
  *
  * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
  * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
+ * They are thrown to the #GMainLoop, however. Read http://live.gnome.org/GdkLock 
+ * for more information.
+ *
+ * Since: 1.0
  **/
 	queue_signals[TASK_REMOVED] =
 		g_signal_new ("task_removed",
@@ -337,6 +355,8 @@
  * o_async_worker_new:
  * @returns: a new queue
  *
+ * Create a new worker
+ * 
  * Since: 1.0
  */
 OAsyncWorker*
@@ -548,13 +568,13 @@
 /**
  * o_async_worker_add:
  * @queue: a #OAsyncWorker
- * @task: the task to add
+ * @task: (callee-owns): the #OAsyncWorkerTask to add
  * @returns: the task_id
  *
- * Will add a task to the queue
+ * Add a task to the queue
  *
  * Since: 1.0
- */
+ **/
 gint
 o_async_worker_add (OAsyncWorker *queue, OAsyncWorkerTask *task)
 {
@@ -571,7 +591,8 @@
 
 		G_LOCK (tasks);
 		queue->priv->tasks = g_list_insert_sorted (queue->priv->tasks, 
-				task, o_async_worker_list_sort_tasks);
+				g_object_ref (task), 
+				o_async_worker_list_sort_tasks);
 
 		task->priv->id = ++queue->priv->idseed;
 		retval = task->priv->id;
@@ -602,14 +623,14 @@
  * @run_callback: whether to still run the callback function
  *
  * Will remove a task from the queue. Note that trying to remove the current 
- * task will fail. If removal succeeded, the task_removed signal will be 
+ * task will fail. If removal succeeded, the @task-removed signal will be 
  * emitted.
  *
  * Once removed, the task will get the state of being cancelled. If the 
  * run_callback argument is TRUE, the callback will still run (for cleaning up)
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_remove (OAsyncWorker *queue, gint task_id, gboolean run_callback)
 {
@@ -672,56 +693,50 @@
 /**
  * o_async_worker_get_current:
  * @queue: a #OAsyncWorker
- * @found: A pointer to a boolean which will be filled in with true or false
- * @returns: a reference to the current task
+ * @found: A pointer to a boolean which will be assigned to TRUE or FALSE
+ * @returns: (caller-owns) (null-ok): the current task or NULL
  *
- * Will return a reference to the task thats is currently being processed by 
- * the queue
+ * Returns the task thats is currently being processed by 
+ * the queue or NULL if none.
  *
  * Since: 1.0
  */
-OAsyncWorkerTask
-o_async_worker_get_current (OAsyncWorker *queue, gboolean *found)
+OAsyncWorkerTask*
+o_async_worker_get_current (OAsyncWorker *queue)
 {
 	OAsyncWorkerTask *retval = NULL;
 
-	if (found)
-		*found = FALSE;
-
 	if (IS_VALID_OBJECT (queue))
 	{
 		G_LOCK(tasks);
 		retval = queue->priv->current;
-		if (found)
-			*found = TRUE;
+		if (retval)
+			g_object_ref (retval);
 		G_UNLOCK(tasks);
 	} else {
 		O_ASYNC_WORKER_OBJECT_NOT_READY(queue);
-		retval = notfound();
+		retval = NULL;
 	}
 
-	return *retval;
+	return retval;
 }
 
 /**
  * o_async_worker_get_with_id:
  * @queue: a #OAsyncWorker
- * @task_id: the id of the task as returned by o_async_worker_add
- * @found: A pointer to a boolean which will be filled in with true or false
- * @returns: a reference to the task
+ * @task_id: the id of the task as returned by @o_async_worker_add
+ * @found: A pointer to a boolean which will be assigned to TRUE or FALSE
+ * @returns: (caller-owns) (null-ok): the current task or NULL
  *
- * Will return a reference to the task that has been identified by task_id
+ * Returns the task that has been identified by task_id or NULL if none.
  *
  * Since: 1.0
- */
-OAsyncWorkerTask
-o_async_worker_get_with_id (OAsyncWorker *queue, gint task_id, gboolean *found)
+ **/
+OAsyncWorkerTask*
+o_async_worker_get_with_id (OAsyncWorker *queue, gint task_id)
 {
 	OAsyncWorkerTask *retval = NULL;
 
-	if (found)
-		*found = FALSE;
-	
 	if (IS_VALID_OBJECT (queue))
 	{
 		gboolean cont = TRUE;
@@ -733,9 +748,7 @@
 			OAsyncWorkerTask *cur = copy->data;
 			if (cur && cur->priv->id == task_id)
 			{
-				retval = cur;
-				if (found)
-					*found = TRUE;
+				retval = g_object_ref (cur);
 				cont = FALSE;
 			}
 			copy = g_list_next (copy);
@@ -747,10 +760,10 @@
 			retval = notfound();
 	} else {
 		O_ASYNC_WORKER_OBJECT_NOT_READY(queue);
-		retval = notfound();
+		retval = NULL;
 	}
 	
-	return *retval;
+	return retval;
 }
 
 void
@@ -815,13 +828,13 @@
  * o_async_worker_add_wait:
  * @queue: a #OAsyncWorker
  * @micros: amount of microseconds the queue will have to wait
- * @priority: the priority of the wait-task
- * @returns: the task_id of the wait-task
+ * @priority: the priority of the waiter task
+ * @returns: the task_id of the waiter task
  * 
  * Will make the queue wait for at least micros microseconds
  *
  * Since: 1.0
- */
+ **/
 gint
 o_async_worker_add_wait (OAsyncWorker *queue, gint micros, gint priority)
 {
@@ -855,10 +868,10 @@
  * o_async_worker_join:
  * @queue: a #OAsyncWorker
  *
- * Waits until the queue finishes
+ * Blocks until the queue finishes
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_join (OAsyncWorker *queue)
 {
@@ -881,12 +894,12 @@
  * @queue: a #OAsyncWorker
  * @mask: the mask parameter for the sched_setaffinity function
  *
- * Will set the CPU affinity of the thread that will process the tasks.
+ * Sets the CPU affinity of the thread that will process the tasks.
  * This will only work on platforms that have support for the 
- * sched_setaffinity function.
+ * sched_setaffinity function (for example Linux).
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_sched_setaffinity (OAsyncWorker *queue, unsigned long *mask)
 {
@@ -906,9 +919,9 @@
  * @queue: a #OAsyncWorker
  * @returns: the mask parameter for the sched_setaffinity function
  *
- * Will get the CPU affinity of the thread that will process the tasks
+ * Get the CPU affinity of the thread that will process the tasks
  * This will only work on platforms that have support for the 
- * sched_setaffinity function.
+ * sched_setaffinity function (for example Linux).
  *
  * Since: 1.0
  */
@@ -933,10 +946,10 @@
  * @param: The const struct sched_param *p of the sched_setscheduler function
  *
  * This will only work on platforms that have support for the 
- * sched_setscheduler function.
+ * sched_setscheduler function (for example Linux).
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_sched_setscheduler(OAsyncWorker *queue, int policy, gpointer param)
 {
@@ -960,10 +973,10 @@
  * @returns: the policy
  *
  * This will only work on platforms that have support for the 
- * sched_getscheduler function.
+ * sched_getscheduler function (for example Linux).
  *
  * Since: 1.0
- */
+ **/
 int
 o_async_worker_sched_getscheduler(OAsyncWorker *queue)
 {

Modified: trunk/liboasyncworker/oasyncworkertask.c
==============================================================================
--- trunk/liboasyncworker/oasyncworkertask.c	(original)
+++ trunk/liboasyncworker/oasyncworkertask.c	Sun Apr 27 11:41:10 2008
@@ -150,16 +150,19 @@
 /**
  * OAsyncWorkerTaskFunc
  * @task: a pointer to the instance of this task
- * @arguments: the arguments that have been set with o_async_worker_task_set_arguments
- * @returns: a gpointer that will also be the second argument of the OAsyncWorkerTaskCallback
+ * @arguments: the arguments that have been set with @o_async_worker_task_set_arguments
+ * @returns: a gpointer that will also be the second argument of the #OAsyncWorkerTaskCallback
  *
- * Using o_async_worker_task_set_func you can assign a function like this one to
- * a task. You can imagine this function as the start of the body of the task.
- * It's what needs to be performed in order to complete the task successfully.
+ * Using @o_async_worker_task_set_func you can assign a function to a task
+ * This function is the body of the task. It's what needs to be performed in order
+ * to complete the task successfully.
  *
  * You can launch new functions from this function. If you don't start a thread
  * in it, they will still belong to the body of the task. If you do start a 
- * thread, the thread function will not be part of the body of this task.
+ * thread, the code running in the thread will not be part of the body of this 
+ * task. A @g_thread_join will of course work as expected. The body of your tasks
+ * will be ran in a thread too. You can join this thread using @o_async_worker_join.
+ * Note that all tasks in the worker will need to finish for the join to return.
  *
  * Cancellation points will only trigger a cancel within the body of a task.
  * That body will stop when you return this function, or when a cancellation
@@ -170,21 +173,32 @@
  * cancellation, that argument will always be NULL (thus unallocated).
  *
  * Since: 1.0
- */
+ **/
 
  /**
   * OAsyncWorkerTaskCallback
   * @task: a pointer to the instance of this task
-  * @func_result : a pointer to the result of the OAsyncWorkerTaskFunc
+  * @func_result : a pointer to the result of the #OAsyncWorkerTaskFunc
   *
   * In this function you need to free all the resources that where allocated
   * for the task. After the callback will the task itself get freed. So it's
   * indeed your last chance to free references and allocations.
   *
-  * If you returned an allocated pointer in the OAsyncWorkerTaskFunc, you'll
-  * need to free it in this callback too. It's the func_result argument.
-  * You can, of course, use this func_result argument to pass information from
-  * the body of the task, to the callback. But make sure you free it afterwards.
+  * If you returned an allocated pointer in the #OAsyncWorkerTaskFunc, you'll
+  * need to free it in this callback too. The returned value of the
+  * #OAsyncWorkerTaskFunc will be the @func_result argument. You can, of course,
+  * use this @func_result argument to pass information from the body of the task,
+  * to the callback. But make sure you free it afterwards.
+  *
+  * Note that if the #OAsyncWorkerTaskFunc returned due to a cancellation, that
+  * @func_result will always be NULL. Deal with it in this callback!
+  *
+  * As this callback happens in the #GMainLoop, you should refrain from doing
+  * lengthy or CPU intensive tasks here. Stick to freeing up resources and 
+  * notifying UI for example. Note that neither AsyncWorker's signals nor these
+  * callbacks happen with the Gdk lock of Gtk+ entered. You must still do the
+  * @gdk_threads_enter and @gdk_threads_leave in the signal handlers and these
+  * callbacks. Read http://live.gnome.org/GdkLock for more information.
   *
   * Since: 1.0
   */
@@ -193,12 +207,7 @@
  * o_async_worker_task_new:
  * @returns: a #OAsyncWorkerTask
  *
- * Will create a new OAsyncWorkerTask
- *
- * The queue will unreference the instance once processing it completed.
- * If you're not adding it to a queue, you'll need to unreference it manually.
- *
- * If you do, you should not unreference it yourself.
+ * Will create a new #OAsyncWorkerTask
  *
  * Since: 1.0
  */
@@ -218,20 +227,15 @@
  * @arguments: a pointer to the arguments
  * @callback: the callback in which you'll need to free the arguments
  *
- * Will create a new OAsyncWorkerTask and will set it's arguments property
- *
- * The queue will unreference the instance once processing it completed.
- * If you're not adding it to a queue, you'll need to unreference it manually.
+ * Creates a new #OAsyncWorkerTask and will set its arguments property
  *
- * If you do, you should not unreference it yourself.
- *
- * You will, however, need to free the arguments pointer in the callback. That's
- * why you need to give a reference to the callback too: If you're not planning
- * to use the callback, you shouldn't set the arguments pointer to an allocated
+ * You will need to free the arguments pointer in the callback. This is why you
+ * need to give a reference to the @callback too: If you're not planning
+ * to use a @callback, you shouldn't set the arguments pointer to an allocated
  * resource.
  *
  * Since: 1.0
- */
+ **/
 OAsyncWorkerTask*
 o_async_worker_task_new_with_arguments (gpointer arguments, OAsyncWorkerTaskCallback callback)
 {
@@ -249,8 +253,9 @@
  * @task: a #OAsyncWorkerTask
  * @arguments: a pointer to the arguments
  *
- * Will set the arguments of the task. The arguments are passed to the launcher
- * function. You'll need to free it in the callback function.
+ * Set the arguments of the @task. The arguments are passed to the launcher
+ * function. You'll need to free it in the callback function which you must
+ * set with @o_async_worker_task_set_callback.
  *
  * It allows you to transfer data to the launcher function. For example function
  * arguments. You can use a GObject or a simple struct. In fact you can use any
@@ -259,10 +264,10 @@
  *
  * If you're not allocating memory (not setting the arguments), you won't need
  * to free it. If you're also returning NULL in the launcher func, you can keep 
- * the callback empty (it won't run).
+ * the callback unassigned.
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_task_set_arguments (OAsyncWorkerTask *task, gpointer arguments)
 {
@@ -283,19 +288,23 @@
  * @task: a #OAsyncWorkerTask
  * @func: a reference to the launcher function
  *
- * Sets the laucher function of a task. It will get as argument a pointer to 
- * arguments property of the task object. You can unwrap this pointer (for 
+ * Sets the laucher function of @task. It will get as argument a pointer to 
+ * arguments property of the @task object. You can unwrap this pointer (for 
  * example a struct) to get the arguments which you might need during the 
- * function itself.
+ * function itself. You set the arguments property using 
+ * @o_async_worker_task_set_arguments.
  *
  * If you're planning to use Gtk+ objects, you'll need to wrap your 
- * gtk-functions with gdk_threads_enter() and gdk_threads_leave(). 
+ * gtk-functions with gdk_threads_enter() and gdk_threads_leave() in the body
+ * of @task (and in code spawn into a thread). Read http://live.gnome.org/GdkLock 
+ * for more information.
  *
  * If you're planning to use non-threadsafe functions and/or objects, make
  * sure that you have proper locking in place.
  *
  * Also read about the callback to know where to free the task-arguments and the
- * result of the launcher function.
+ * result of the launcher function. You set the callback using
+ * @o_async_worker_task_set_callback
  *
  * There's more information at the OAsyncWorkerTaskFunc section
  *
@@ -326,29 +335,32 @@
  * launcher function.
  *
  * If you're planning to use Gtk+ objects, you'll need to wrap your 
- * gtk-functions with gdk_threads_enter() and gdk_threads_leave(). 
+ * gtk-functions with gdk_threads_enter() and gdk_threads_leave() in the body of
+ * @callback (and in code spawn into a thread). Read http://live.gnome.org/GdkLock
+ * for more information.
  *
  * If you're planning to use non-threadsafe functions and/or objects, make
  * sure that you have proper locking in place.
  *
- * The callback is also responsible for freeing (or unreferencing) the 
+ * The @callback is for example responsible for freeing (or unreferencing) the 
  * arguments property (pointer) of the task and the result of the laucher 
- * function. If you don't free it in the callback, it's possible that you'll 
+ * function. If you don't free it in the callback, it's likely that you'll 
  * have memory-leaks.
  *
- * You can't make a cancellation point trigger a cancel in the callback.
+ * You can't make a cancellation point trigger a cancel in the @callback.
  * Therefore will the callback always run. It can't be preempted. You can
  * instruct a cancellation point to launch the callback after cancelling.
- * This way you can free the resources of a finished, removed or cancelled task
- * in the callback.
+ * This way you can free the resources of a finished, removed or cancelled 
+ * task in the callback. Check out @o_async_worker_task_cancel_point for
+ * more information about this.
  *
  * If you're not setting the arguments property and you returned NULL in the 
- * launcher func, you can ignore the callback.
+ * launcher func, you can leave the callback unassigned.
  *
- * There's more information at the OAsyncWorkerTaskCallback section
+ * There's more information at the #OAsyncWorkerTaskCallback section
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_task_set_callback (OAsyncWorkerTask *task, OAsyncWorkerTaskCallback callback)
 {
@@ -370,7 +382,7 @@
  * @returns: a pointer to the arguments
  *
  * Since: 1.0
- */
+ **/
 gpointer
 o_async_worker_task_get_arguments (OAsyncWorkerTask *task)
 {
@@ -392,7 +404,7 @@
  * @returns: a reference to the function
  *
  * Since: 1.0
- */
+ **/
 OAsyncWorkerTaskFunc
 o_async_worker_task_get_func (OAsyncWorkerTask *task)
 {
@@ -414,7 +426,7 @@
  * @returns: a reference to the callback function
  *
  * Since: 1.0
- */
+ **/
 OAsyncWorkerTaskCallback
 o_async_worker_task_get_callback (OAsyncWorkerTask *task)
 {
@@ -433,30 +445,30 @@
 /**
  * o_async_worker_task_get_queue:
  * @task: a #OAsyncWorkerTask
- * @returns: a pointer to the OAsyncWorker
+ * @returns: (caller-owns) (null-ok): a pointer to the #OAsyncWorker or NULL
  *
- * Will return a pointer (therefore it's not threadsafe) to the queue that is
- * assigned to process the task. It will return NULL if no queue has been
- * assigned.
+ * Returns a pointer to the queue that is assigned to process the task. It 
+ * will return NULL if no queue has been assigned.
  *
  * Don't use this function in threads. Don't use it in the launcher and/or
  * callback functions of the task.
  * 
  * Since: 1.0
- */
-gpointer
+ **/
+OAsyncWorker*
 o_async_worker_task_get_queue (OAsyncWorkerTask *task)
 {
 	OAsyncWorker* retval = NULL;
 
 	if (IS_VALID_OBJECT(task))
 	{
-		retval = task->priv->queue;
+		if (task->priv->queue)
+			retval = g_object_ref (task->priv->queue);
 	} else {
 		O_ASYNC_WORKER_OBJECT_NOT_READY(task);
 	}
 
-	return (gpointer)retval;
+	return retval;
 }
 
 /**
@@ -467,7 +479,7 @@
  * Will return the priority of a task
  *
  * Since: 1.0
- */
+ **/
 gint
 o_async_worker_task_get_priority (OAsyncWorkerTask *task)
 {
@@ -495,7 +507,7 @@
  * being set.
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_task_set_priority (OAsyncWorkerTask *task, gint priority)
 {
@@ -503,11 +515,12 @@
 	{
 		LOCK_OBJECT(task);
 		{
-			OAsyncWorker *queue = o_async_worker_task_get_queue
-				(task);
+			OAsyncWorker *queue = o_async_worker_task_get_queue (task);
 			task->priv->priority = priority;
-			if (queue)
+			if (queue) {
 				_o_async_worker_sort_tasks (queue);
+				g_object_unref (queue);
+			}
 		}
 		UNLOCK_OBJECT(task);
 	} else {
@@ -539,8 +552,6 @@
 	{
 		LOCK_OBJECT(task);
 		{
-			OAsyncWorker *queue = o_async_worker_task_get_queue
-				(task);
 			task->priv->id = id;
 		}
 		UNLOCK_OBJECT(task);
@@ -561,12 +572,12 @@
  * the cancellation features.
  *
  * Note that to be cancelled, the task really needed to get cancelled. The
- * o_async_worker_task_cancel method only requests a cancellation. The task then
+ * @o_async_worker_task_cancel method only requests a cancellation. The task then
  * still needs to get at a cancellation point. Only then will this property will
  * be set.
  *
  * Since: 1.0
- */
+ **/
 gboolean
 o_async_worker_task_is_cancelled (OAsyncWorkerTask *task)
 {
@@ -595,11 +606,11 @@
  *
  * You won't need to free the result of the launcher function since it wont get
  * the chance to return the value (else it wasn't cancelled). You can use 
- * o_async_worker_task_is_cancelled to know, in that callback, whether the task
+ * @o_async_worker_task_is_cancelled to know, in that callback, whether the task
  * was cancelled.
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_task_cancel_point (OAsyncWorkerTask *task, gboolean run_callback)
 {
@@ -632,13 +643,13 @@
  * 
  * Set a task to be cancelled. The cancellation itself will only trigger when
  * during the processing of the task-body, a cancellation point is found.
- * Also see the information about o_async_worker_task_cancel_point!
+ * Also see the information about @o_async_worker_task_cancel_point.
  *
- * Note that you need to setup a GMainLoop for this to work correctly. All
+ * Note that you need to setup a #GMainLoop for this to work correctly. All
  * Gtk+ applications (after doing gtk_main) have this.
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_task_request_cancel (OAsyncWorkerTask *task)
 {

Modified: trunk/samples/printqueue/main.c
==============================================================================
--- trunk/samples/printqueue/main.c	(original)
+++ trunk/samples/printqueue/main.c	Sun Apr 27 11:41:10 2008
@@ -167,7 +167,8 @@
         g_print("\n[main] Adding print job %d with %d pages\n", job->id, job->pages);
 
         /* Add the job to the queue */
-        o_async_worker_add(queue, task);    
+        o_async_worker_add(queue, task);
+	g_object_unref (task);
 }
 
 gint

Modified: trunk/samples/simple/main.c
==============================================================================
--- trunk/samples/simple/main.c	(original)
+++ trunk/samples/simple/main.c	Sun Apr 27 11:41:10 2008
@@ -58,6 +58,8 @@
 	
 	o_async_worker_add (queue, dummy);
 	
+	g_object_unref (dummy);
+
 	if (cancel)
 	{
 		o_async_worker_task_request_cancel (dummy);

Modified: trunk/samples/treeview/main.c
==============================================================================
--- trunk/samples/treeview/main.c	(original)
+++ trunk/samples/treeview/main.c	Sun Apr 27 11:41:10 2008
@@ -119,15 +119,11 @@
 static void
 queue_task_show_handler (OAsyncWorker *queue, gint task_id, gpointer user_data)
 {
-	gboolean found=FALSE;
-	OAsyncWorkerTask task = o_async_worker_get_with_id 
-		(queue, task_id, &found);
+	OAsyncWorkerTask *task = o_async_worker_get_with_id (queue, task_id);
 	
-	if (found)
-	{
+	if (task) {
 		treequeue_t *treequeue = user_data;
 		GtkTreeView *treeview = treequeue->treeview;
-		OAsyncWorkerTask *toadd = &task;
 		
 		GtkTreeIter iter;
 		GtkListStore *store = GTK_LIST_STORE 
@@ -135,8 +131,8 @@
 
 		g_print ("An task needs to be added to the treeview\n");
 
-		gchar *arguments = o_async_worker_task_get_arguments (&task);
-		gint priority = o_async_worker_task_get_priority (&task);
+		gchar *arguments = o_async_worker_task_get_arguments (task);
+		gint priority = o_async_worker_task_get_priority (task);
 
 		gtk_list_store_append (store, &iter);
 
@@ -146,7 +142,9 @@
 			g_strdup(arguments), -1); /* Copy! */
 		gtk_list_store_set (store, &iter, PRIORITY_COLUMN, priority, -1);
 		gtk_list_store_set (store, &iter, ID_COLUMN, task_id, -1);
-		gtk_list_store_set (store, &iter, TASK_COLUMN, toadd, -1);
+		gtk_list_store_set (store, &iter, TASK_COLUMN, task, -1);
+
+		g_object_unref (task);
 
 	}
 	
@@ -168,7 +166,9 @@
         o_async_worker_task_set_callback (dummy, dummy_callback);
         o_async_worker_task_set_priority (dummy, prio++);
 
-        o_async_worker_add (queue, dummy);	
+        o_async_worker_add (queue, dummy);
+
+	g_object_unref (dummy);
 }
 
 static void
@@ -204,16 +204,15 @@
 
 	if (gtk_tree_selection_get_selected(selection, &model, &iter))
 	{
-		gboolean found = FALSE;
-		OAsyncWorkerTask task;
+		OAsyncWorkerTask *task;
 		gint task_id = -1;
 		
 		gtk_tree_model_get (model, &iter, ID_COLUMN, &task_id, -1);		
-		task = o_async_worker_get_with_id (queue, task_id, &found);
+		task = o_async_worker_get_with_id (queue, task_id);
 		
-		if (found)
-		{
-			o_async_worker_task_request_cancel (&task);
+		if (task) {
+			o_async_worker_task_request_cancel (task);
+			g_object_unref (task);
 		}
 	}
 }
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]