#include "el_common.h"
#include "el_clock.h"

Typedefs
typedef void(*	el_timer_callback )(void *)

Functions
el_handle	el_create_timer (void)
	create a timer in the system More...

void	el_delete_timer (el_handle h)
	delete the timer More...

void	el_timer_set_periodic (el_handle h, el_bool b)
	set whether the timer repeat the countdown process once a countdown is finished More...

void	el_timer_set_callback (el_handle h, el_timer_callback func, void *arg)
	set the callback of a timer More...

void	el_timer_start (el_handle h, el_time t_ms)
	specify the countdown time and start the timer More...

void	el_timer_start_fraction (el_handle h, int num, int den)
	specify the countdown time using a fraction and start the timer More...

void	el_timer_pause (el_handle h)
	pause the countdown of the timer More...

void	el_timer_resume (el_handle h)
	resume the countdown of the timer More...

el_handle	el_timer_callback_get_handle ()
	get the handle of the timer in a timer callback More...

el_uint32	el_timer_get_rounds (el_handle h)
	get the rounds of the timer More...

void	el_timer_set_rounds (el_handle h, el_uint32 n)
	set the rounds of the timer More...

Detailed Description

Author: Jianing Chen

Function Documentation

el_handle el_create_timer ( void )

create a timer in the system

Returns: handle of the timer

This function create a timer in the system. It returns a handle to the timer created. This handle is used to refer the timer in the related functions.

This function returns NULL if the creation is failed.

void el_delete_timer ( el_handle h )

delete the timer

Parameters

h	handle of the timer

void el_timer_set_periodic	(	el_handle	h,
		el_bool	b
	)

set whether the timer repeat the countdown process once a countdown is finished

Parameters

h	handle of the timer
b	is periodic or not

void el_timer_set_callback	(	el_handle	h,
		el_timer_callback	func,
		void *	arg
	)

set the callback of a timer

Parameters

h	handle of the timer
func	pointer to the function to be called when the timer expired
arg	the argument passed to the callback function when it is called

When the timer's countdown is finished, the time's callback "func" will be called as "func(arg);". This callback need to be a function with no wait/delay inside or any code with high computational cost.

A periodic timer with a callback can achieve the similar functionality of the 'agenda' in the official e-puck library, which creates a periodic routine in the system.

Compared to a loop with time wait in a process, using timer callback to run a periodic routine has no accumulated error. For example, a timer with 50 ms period can accurately run its callback for 72000 times in one hour. If it is written inside a process as a loop with 50 ms wait, the looping times will be slightly less than 72000 due to the time cost of the loop body.

Use NULL for 'func' if no callback function are needed. By default, the timer does not has a callback function.

void el_timer_start	(	el_handle	h,
		el_time	t_ms
	)

specify the countdown time and start the timer

Parameters

h	handle of the timer
t_ms	period in millisecond

Start the countdown. Note, the actual countdown operation is applied in the el_main_loop while no process is running. Thus, if a process does not return or cooperate/wait during its execution, no timer countdown can be handled properly. For example, the following mechanism will lead to a infinite loop:

 ...
 my_timer = el_create_timer();
 el_timer_start( my_timer, 1000 );
 while( el_timer_get_rounds( my_timer ) == 0 ){
 }
 el_led_set( 0, EL_ON );// this line will never be reached
 el_delete_timer( my_timer );
 ...

Instead, a process cooperation need to be used:

 ...
 my_timer = el_create_timer();
 el_timer_start( my_timer, 1000 );
 while( el_timer_get_rounds( my_timer ) == 0 ){
     el_process_cooperate();// this gives the timer system a chance to handle all timers
 }
 el_led_set( 0, EL_ON );
 el_delete_timer( my_timer );
 ...

void el_timer_start_fraction	(	el_handle	h,
		int	num,
		int	den
	)

specify the countdown time using a fraction and start the timer

Parameters

h	handle of the timer
num	numerator of the period in second
den	denominator of the period in second

The countdown time of the timer is (num/den) sec.

void el_timer_pause ( el_handle h )

pause the countdown of the timer

Parameters

h	handle of the timer

void el_timer_resume ( el_handle h )

resume the countdown of the timer

Parameters

h	handle of the timer

This only applies to a started timer.

el_handle el_timer_callback_get_handle ( )

get the handle of the timer in a timer callback

Returns: handle of the timer

This function must be used within a timer callback.

el_uint32 el_timer_get_rounds ( el_handle h )

get the rounds of the timer

Parameters

h	handle of the timer

Returns: number of times that the countdown has been finished

This function returns the number of times that the countdown has been finished. When the timer is started, its round counter will be set to 0. Each time the timer's countdown finishes, its 'rounds' will +1. Thus, for a on-going timer that is periodic (set using el_timer_set_periodic), its rounds will keep increasing.

void el_timer_set_rounds	(	el_handle	h,
		el_uint32	n
	)

set the rounds of the timer

Parameters

h	handle of the timer
n	rounds to be used

This function is used to manually modify the rounds of a timer. It is mainly used to reset the rounds of a timer to 0.

Typedefs

Functions

Detailed Description

Function Documentation