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.



SVN revision: 60557

legacy/ecore/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
 

legacy/ecore/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();
+}

legacy/ecore/src/lib/ecore/Ecore.h

@@ -837,6 +837,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
    *

legacy/ecore/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)

legacy/ecore/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
+ *
  * @{
  */