Timer event handling.

---

Detailed Description

The event library provides support for timer manipulation. Timers are a way to have events occur at specific times or intervals. There are three basic types of timers:

• Absolute Timers
  Absolute timers generate an ET_EXPIRE event at or after the absolute time specified in the call to timer_create().

• Relative Timers
  Relative timers generate an ET_EXPIRE event at or after the time interval specified in the call to timer_create() has elapsed.

• Periodic Timers
  Periodic timers are similar to relative timers, except that they are reset after they expire. They should be used when an event is desired at a fixed, repeating interval.

Files
file	tim.h
	Timer event system header file.
Data Structures
struct	_ev_timnode_s
	Timer node structure. More...
struct	_ev_tim_s
	Timer generator structure. More...
Defines
#define	EV_TIM_MAGIC
	Timer generator magic number.
#define	ti_verify(tim)
	Timer generator verification macro.
#define	ti_type(tim)
	Timer type.
#define	ti_value(tim)
	Timer value.
#define	ti_expire(tim)
	Timer expiration time.
Typedefs
typedef _ev_tim_s	ev_tim_t
	Timer generator.
typedef _ev_timnode_s	_ev_timnode_t
	Timer node.
Enumerations
enum	ev_timtype_t { TT_ABSOLUTE, TT_RELATIVE, TT_PERIODIC }
	Timer types. More...
Functions
ev_err_t	timer_create (ev_ctx_t *ctx, ev_timtype_t type, struct timeval *value, ev_call_t call, void *data, ev_tim_t **tim_p)
	Create a timer.
ev_err_t	timer_resched (ev_ctx_t *ctx, ev_tim_t *tim, ev_timtype_t type, struct timeval *value)
	Reschedule an existing timer.
ev_err_t	timer_destroy (ev_ctx_t *ctx, ev_tim_t *tim)
	Destroy an existing timer.

---

Define Documentation

#define EV_TIM_MAGIC

This is the magic number used for the timer generator structure. Definition at line 117 of file tim.h. Referenced by event_init(), and main().

#define ti_expire (  tim   )

This macro returns the absolute expiration time for this timer, as computed by timer_create() or timer_resched() (or upon timer expiration, for TT_PERIODIC timers). Parameters: [in]  tim  A pointer to an ev_tim_t. Returns: A pointer to a struct timeval containing the expiration time for this timer. Definition at line 168 of file tim.h. Referenced by main().

#define ti_type (  tim   )

This macro returns the type of the given timer. Parameters: [in]  tim  A pointer to an ev_tim_t. Returns: One of TT_ABSOLUTE, TT_RELATIVE, or TT_PERIODIC, indicating which type of timer this is. Definition at line 142 of file tim.h. Referenced by main().

#define ti_value (  tim   )

This macro returns the original time that was passed in the call to timer_create(). For TT_PERIODIC timers, this is the relative time for which the timer will be reset upon expiration. Parameters: [in]  tim  A pointer to an ev_tim_t. Returns: A pointer to a struct timeval containing the original time passed in the call to timer_create(). Definition at line 155 of file tim.h. Referenced by main().

#define ti_verify (  tim   )

This macro verifies that a given pointer actually does point to an ev_tim_t. Warning: This macro evaluates the tim argument twice. Parameters: [in]  tim  A pointer to an ev_tim_t. Returns: Boolean true if sock is a valid timer generator or false otherwise. Definition at line 131 of file tim.h. Referenced by timer_destroy(), and timer_resched().

---

Typedef Documentation

typedef struct _ev_timnode_s _ev_timnode_t

For internal use only. Timers are stored in a priority queue. This structure specifies an entry on the timer queue. Definition at line 74 of file tim.h.

typedef struct _ev_tim_s ev_tim_t

Timers are described using this structure. Definition at line 66 of file tim.h.

---

Enumeration Type Documentation

enum ev_timtype_t

All timers have a timer type describing the kind of timer that is set. Enumerator: TT_ABSOLUTE  Timer has an absolute expiration time. TT_RELATIVE  Timer has a relative expiration time. TT_PERIODIC  Timer expires periodically. Definition at line 81 of file tim.h.

---

Function Documentation

ev_err_t timer_create (  ev_ctx_t *  ctx, ev_timtype_t  type, struct timeval *  value, ev_call_t  call, void *  data, ev_tim_t **  tim_p )

This function creates and schedules a timer for the specified time. If the tim_p parameter is not NULL, it will be used to return a pointer to the created timer. Test: This function is tested in t_timer_fcns.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  type  One of TT_ABSOLUTE, TT_RELATIVE, or TT_PERIODIC, to specify the desired timer type. [in]  value  The timer's expiration time, either an absolute time (e.g., for TT_ABSOLUTE timers), or a relative time (for TT_RELATIVE or TT_PERIODIC timers). [in]  call  The callback function for the library to use. If NULL, the library may not be used in the event loop mode. [in]  data  Any application-specific data that must be passed to the callback function. [out]  tim_p  A pointer to a pointer to an ev_tim_t. A NULL value may be passed if the application does not need a pointer to the timer. Return values: EINVAL  An invalid argument was given. ENOMEM  Out of memory. Definition at line 82 of file timer_create.c. References _timer_insert(), _ev_ctx_s::ec_timer, ec_verify, eg_callback_set, eg_calldata_set, eg_ref_inc, EGT_TIMER, _ev_englist_s::el_first, _ev_englink_s::el_next, _ev_englink_s::el_prev, eng_tim_add, eng_tim_rem, _ev_engine_s::eng_timer, _ev_timers_s::eti_active, ev_init, ev_return, event_gen_alloc(), event_gen_release(), ti_expire_comp, _ev_tim_s::ti_type, _ev_tim_s::ti_value, TT_ABSOLUTE, TT_PERIODIC, and TT_RELATIVE. Referenced by main(). Here is the call graph for this function:

ev_err_t timer_destroy (  ev_ctx_t *  ctx, ev_tim_t *  tim )

This function is used to destroy an existing timer. It may be used from the event callback for TT_PERIODIC timers. Test: This function is tested in t_timer_fcns.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  tim  A pointer to the ev_tim_t to be destroyed. Return values: EINVAL  An invalid argument was given. Definition at line 109 of file timer_destroy.c. References _timer_untree(), _ev_ctx_s::ec_timer, ec_verify, eg_context, eg_flags, eg_flags_set, eg_ref_dec, _ev_englist_s::el_last, _ev_englink_s::el_prev, eng_tim_rem, _ev_engine_s::eng_timer, _ev_timers_s::eti_active, EV_GEN_DELETED, ev_init, ev_return, and ti_verify. Referenced by _timer_insert(), main(), and timer_resched(). Here is the call graph for this function:

ev_err_t timer_resched (  ev_ctx_t *  ctx, ev_tim_t *  tim, ev_timtype_t  type, struct timeval *  value )

Sometimes, a timer must be rescheduled. This function provides a means for doing that. The function may be used from the event callback for the timer. Test: This function is tested in t_timer_fcns.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  tim  A pointer to an ev_tim_t to be rescheduled. [in]  type  One of TT_ABSOLUTE, TT_RELATIVE, or TT_PERIODIC, to specify the desired type for the rescheduled timer. [in]  value  The timer's new expiration time, either an absolute time (e.g., for TT_ABSOLUTE timers), or a relative time (for TT_RELATIVE or TT_PERIODIC timers). Return values: EINVAL  An invalid argument was given. Definition at line 32 of file timer_resched.c. References _timer_heapify_down(), _timer_heapify_up(), _timer_insert(), _timer_untree(), _ev_ctx_s::ec_timer, ec_verify, eg_context, eg_flags, eg_flags_clr, eg_flags_set, eg_ref_dec, _ev_englist_s::el_first, _ev_englist_s::el_last, _ev_englink_s::el_next, _ev_englink_s::el_prev, eng_tim_add, eng_tim_rem, _ev_engine_s::eng_timer, _ev_timers_s::eti_active, EV_GEN_DELETED, ev_init, ev_return, _ev_tim_s::ti_expire, ti_expire_comp, _ev_tim_s::ti_type, _ev_tim_s::ti_value, ti_verify, timer_destroy(), TT_ABSOLUTE, TT_PERIODIC, TT_RELATIVE, and tv_comp. Referenced by main(). Here is the call graph for this function:

---