From: antognolli <antognolli@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Date: Wed, 22 Jun 2011 20:54:32 +0000 (+0000)
Subject: ecore/job - Improve documentation and add an example.
X-Git-Tag: build/2012-07-04.173327~1132
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9168eb0787d5a3d602d3d73b843193b8148d8a06;p=profile%2Fivi%2Fecore.git

ecore/job - Improve documentation and add an example.



git-svn-id: http://svn.enlightenment.org/svn/e/trunk/ecore@60608 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33
---

diff --git a/doc/examples.dox b/doc/examples.dox
index 07c59cb..f8e0924 100644
--- a/doc/examples.dox
+++ b/doc/examples.dox
@@ -98,6 +98,24 @@
  */
 
 /**
+ * @page ecore_job_example_c ecore_job - Queuing tasks
+ *
+ * This example shows how an @ref Ecore_Job can be added, how it can be
+ * deleted, and that they always execute in the added order.
+ *
+ * First, 2 callback functions are declared, one that prints strings passed to
+ * it in the @c data pointer, and another one that quits the main loop. In the
+ * @c main function, 3 jobs are added using the first callback, and another one
+ * is added using the second one.
+ *
+ * Then the second added job is deleted just to demonstrate the usage of
+ * ecore_job_del(), and the main loop is finally started. Run this example to
+ * see that @c job1, @c job3 and @c job_quit are ran, in this order.
+ *
+ * @include ecore_job_example.c
+ */
+
+/**
  * @example ecore_idler_example.c
  * This example shows when @ref Ecore_Idler, @ref Ecore_Idle_Enterer and @ref
  * Ecore_Idle_Exiter are called. See
@@ -105,6 +123,12 @@
  */
 
 /**
+ * @example ecore_job_example.c
+ * This example shows how to use an @ref Ecore_Job. See
+ * @ref ecore_job_example_c "the explanation here".
+ */
+
+/**
  * @example ecore_time_example.c
  * Shows the difference between the three time functions. See @ref
  * ecore_time_example_c "the example explained".
diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 088e64b..f909e35 100644
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -14,6 +14,7 @@ LDADD = \
 SRCS = \
 	ecore_idler_example.c \
 	ecore_time_example.c \
+	ecore_job_example.c \
 	client_bench.c \
 	server_bench.c \
 	ecore_con_client_example.c \
@@ -33,6 +34,7 @@ endif
 if EFL_BUILD_EXAMPLES
 pkglib_PROGRAMS += \
 	ecore_idler_example \
+	ecore_job_example \
 	ecore_time_example
 endif
 
diff --git a/src/examples/ecore_job_example.c b/src/examples/ecore_job_example.c
new file mode 100644
index 0000000..1d28b7b
--- /dev/null
+++ b/src/examples/ecore_job_example.c
@@ -0,0 +1,48 @@
+#include <Ecore.h>
+#include <unistd.h>
+
+static void
+_job_print_cb(void *data)
+{
+   char *str = data;
+
+   printf("%s\n", str);
+}
+
+static void
+_job_quit_cb(void *data)
+{
+   ecore_main_loop_quit();
+}
+
+int main(int argc, char **argv)
+{
+   Ecore_Job *job1, *job2, *job3, *job_quit;
+   char *str1 = "Job 1 started.";
+   char *str2 = "Job 2 started.";
+   char *str3 = "Job 3 started.";
+
+   if (!ecore_init())
+     {
+	printf("ERROR: Cannot init Ecore!\n");
+	return -1;
+     }
+
+   job1 = ecore_job_add(_job_print_cb, str1);
+   job2 = ecore_job_add(_job_print_cb, str2);
+   job3 = ecore_job_add(_job_print_cb, str3);
+
+   job_quit = ecore_job_add(_job_quit_cb, NULL);
+   printf("Created jobs 1, 2, 3 and quit.\n");
+
+   if (job2)
+     {
+	char *str;
+	str = ecore_job_del(job2);
+	job2 = NULL;
+	printf("Deleted job 2. Its data was: \"%s\"\n", str);
+     }
+
+   ecore_main_loop_begin();
+   ecore_shutdown();
+}
diff --git a/src/lib/ecore/ecore_job.c b/src/lib/ecore/ecore_job.c
index 0ab34ce..1a95af6 100644
--- a/src/lib/ecore/ecore_job.c
+++ b/src/lib/ecore/ecore_job.c
@@ -47,6 +47,15 @@ _ecore_job_shutdown(void)
  * You can queue jobs that are to be done by the main loop when the current
  * event is dealt with.
  *
+ * Jobs are processed by the main loop similarly to events. They also will be
+ * executed in the order which they were added.
+ *
+ * A good use for them is when you don't want to execute an action immeditately,
+ * but want to give the control back to the main loop so that it will call your
+ * job callback when jobs start being processed (and if there are other jobs
+ * added before yours, they will be processed first). This also gives the chance
+ * to other actions in your program to cancel the job before it is started.
+ *
  * @{
  */