ecore/time - Add an example to use the ecore_time_* functions.

It exemplifies the difference between ecore_time_get(), ecore_time_unix_get()
and ecore_loop_time_get(). A description of this example is also provided.

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

diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index ea1964e..42b1f6a 100644 (file)
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -12,6 +12,7 @@ LDADD = \
        @dlopen_libs@ @EINA_LIBS@ @EVIL_LIBS@ @GLIB_LIBS@ @WIN32_LIBS@ @LTLIBINTL@ @EFL_PTHREAD_LIBS@ @rt_libs@ -lm
 
 SRCS = \
+       ecore_time_example.c \
        client_bench.c \
        server_bench.c \
        ecore_con_client_example.c \
@@ -29,6 +30,7 @@ files_DATA = $(SRCS)
 endif
 
 if EFL_BUILD_EXAMPLES
-pkglib_PROGRAMS +=
+pkglib_PROGRAMS += \
+       ecore_time_example
 endif
 

diff --git a/src/examples/ecore_time_example.c b/src/examples/ecore_time_example.c
new file mode 100644 (file)
index 0000000..5fa5d60
--- /dev/null
+++ b/src/examples/ecore_time_example.c
@@ -0,0 +1,32 @@
+#include <Ecore.h>
+#include <unistd.h>
+
+static Eina_Bool
+_timer_cb(void *data)
+{
+   printf("ecore time: %0.3f\n", ecore_time_get());
+   printf("loop time: %0.3f\n", ecore_loop_time_get());
+   printf("unix time: %0.3f\n", ecore_time_unix_get());
+   printf("\nSleep for 1 second...\n\n");
+   sleep(1);
+   printf("ecore time: %0.3f\n", ecore_time_get());
+   printf("loop time: %0.3f\n", ecore_loop_time_get());
+   printf("unix time: %0.3f\n", ecore_time_unix_get());
+
+   ecore_main_loop_quit();
+
+   return EINA_FALSE;
+}
+
+int main(int argc, char **argv)
+{
+   if (!ecore_init())
+     {
+       printf("ERROR: Cannot init Ecore!\n");
+       return -1;
+     }
+
+   ecore_timer_add(0.1, _timer_cb, NULL);
+   ecore_main_loop_begin();
+   ecore_shutdown();
+}

diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h
index 19d9540..35489fb 100644 (file)
--- a/src/lib/ecore/Ecore.h
+++ b/src/lib/ecore/Ecore.h
@@ -838,6 +838,30 @@ extern "C" {
    */
 
   /**
+   * @page ecore_time_example_c ecore_time - Differences between time functions
+   *
+   * This example shows the difference between calling ecore_time_get(),
+   * ecore_loop_time_get() and ecore_time_unix_get().
+   *
+   * It initializes ecore, then sets a timer with a callback that, when called,
+   * will retrieve the system time using these 3 different functions. After
+   * displaying the time, it sleeps for 1 second, then call display the time
+   * again using the 3 functions.
+   *
+   * Since everything occurs inside the same mainloop iteration, the internal
+   * ecore time variable will not be updated, and calling ecore_loop_time_get()
+   * before and after the sleep() call will return the same result.
+   *
+   * The two other functions will return a difference of 1 second, as expected.
+   *
+   * @note The usage of ecore_loop_time_get() should be preferred against the
+   * two other functions, since it won't produce a system call to get the
+   * current time.
+   *
+   * @include ecore_time_example.c
+   */
+
+  /**
    * @defgroup Ecore_Time_Group Ecore Time functions
    *
    * @{

diff --git a/src/lib/ecore/ecore_time.c b/src/lib/ecore/ecore_time.c
index 2bd5fa6..70efe5f 100644 (file)
--- a/src/lib/ecore/ecore_time.c
+++ b/src/lib/ecore/ecore_time.c
@@ -54,6 +54,8 @@ double _ecore_time_loop_time = -1.0;
  *         when the machine was booted, unix time, etc), all it is
  *         defined is that it never goes backwards (unless you got big critical
  *         messages when the application started).
+ *
+ * @see @ref ecore_time_example_c
  */
 EAPI double
 ecore_time_get(void)
@@ -88,6 +90,8 @@ ecore_time_get(void)
  * @see ecore_loop_time_get().
  *
  * @return  The number of seconds since 12.00AM 1st January 1970.
+ *
+ * @see @ref ecore_time_example_c
  */
 EAPI double
 ecore_time_unix_get(void)
@@ -122,6 +126,8 @@ ecore_time_unix_get(void)
  *         when the machine was booted, unix time, etc), all it is
  *         defined is that it never goes backwards (unless you got big critical
  *         messages when the application started).
+ *
+ * @see @ref ecore_time_example_c
  */
 EAPI double
 ecore_loop_time_get(void)

diff --git a/src/lib/ecore/ecore_timer.c b/src/lib/ecore/ecore_timer.c
index b6ab05c..36f8c1d 100644 (file)
--- a/src/lib/ecore/ecore_timer.c
+++ b/src/lib/ecore/ecore_timer.c
@@ -62,6 +62,9 @@ static double       precision = 10.0 / 1000000.0;
  *
  * The timer allows callbacks to be called at specific intervals.
  *
+ * Examples with functions that deal with time:
+ * @li @ref ecore_time_example_c
+ *
  * @{
  */