tw_timer_template.h File Reference

TW timer template header file, do not compile directly. More...

Include dependency graph for tw_timer_template.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	TWT
struct	tw_timer_wheel_slot_t
struct	TWT

Macros
#define	TWT(a)   __twt(a,TW_SUFFIX)
#define	TW(a)   __tw(a,TW_SUFFIX)

Enumerations
enum	tw_ring_index_t { TW_TIMER_RING_FAST, TW_TIMER_RING_SLOW, TW_TIMER_RING_GLACIER }

Functions
typedef	CLIB_PACKED (struct { u8 timer_id;u32 pool_index;u32 handle;}) TWT(trace)
u32 TW()	tw_timer_start (TWT(tw_timer_wheel) *tw, u32 pool_index, u32 timer_id, u64 interval)
	Start a Tw Timer. More...
void TW()	tw_timer_stop (TWT(tw_timer_wheel) *tw, u32 handle)
	Stop a tw timer. More...
int TW()	tw_timer_handle_is_free (TWT(tw_timer_wheel) *tw, u32 handle)
void TW()	tw_timer_update (TWT(tw_timer_wheel) *tw, u32 handle, u64 interval)
	Update a tw timer. More...
void TW()	tw_timer_wheel_init (TWT(tw_timer_wheel) *tw, void *expired_timer_callback, f64 timer_interval, u32 max_expirations)
	Initialize a tw timer wheel template instance. More...
void TW()	tw_timer_wheel_free (TWT(tw_timer_wheel) *tw)
	Free a tw timer wheel template instance. More...
u32 *TW()	tw_timer_expire_timers (TWT(tw_timer_wheel) *tw, f64 now)
u32 *TW()	tw_timer_expire_timers_vec (TWT(tw_timer_wheel) *tw, f64 now, u32 *vec)

Detailed Description

TW timer template header file, do not compile directly.

Instantiation of tw_timer_template.h generates named structures to implement specific timer wheel geometries. Choices include: number of timer wheels (currently, 1 or 2), number of slots per ring (a power of two), and the number of timers per "object handle".

Internally, user object/timer handles are 32-bit integers, so if one selects 16 timers/object (4 bits), the resulting timer wheel handle is limited to 2**28 objects.

Here are the specific settings required to generate a single 2048 slot wheel which supports 2 timers per object:

#define TW_TIMER_WHEELS 1
#define TW_SLOTS_PER_RING 2048
#define TW_RING_SHIFT 11
#define TW_RING_MASK (TW_SLOTS_PER_RING -1)
#define TW_TIMERS_PER_OBJECT 2
#define LOG2_TW_TIMERS_PER_OBJECT 1
#define TW_SUFFIX _2t_1w_2048sl

See tw_timer_2t_1w_2048sl.h for a complete example.

tw_timer_template.h is not intended to be #included directly. Client codes can include multiple timer geometry header files, although extreme caution would required to use the TW and TWT macros in such a case.

API usage example:

Initialize a two-timer, single 2048-slot wheel w/ a 1-second timer granularity:

tw_timer_wheel_init_2t_1w_2048sl (&tm->single_wheel,
                                 expired_timer_single_callback,
                                  1.0 / * timer interval * / );

Start a timer:

handle = tw_timer_start_2t_1w_2048sl (&tm->single_wheel, elt_index,
                                      [0 | 1] / * timer id * / ,
                                      expiration_time_in_u32_ticks);

Stop a timer:

tw_timer_stop_2t_1w_2048sl (&tm->single_wheel, handle);

Expired timer callback:

static void
expired_timer_single_callback (u32 * expired_timers)
{
    int i;
    u32 pool_index, timer_id;
    tw_timer_test_elt_t *e;
    tw_timer_test_main_t *tm = &tw_timer_test_main;

    for (i = 0; i < vec_len (expired_timers);
        {
        pool_index = expired_timers[i] & 0x7FFFFFFF;
        timer_id = expired_timers[i] >> 31;

        ASSERT (timer_id == 1);

        e = pool_elt_at_index (tm->test_elts, pool_index);

        if (e->expected_to_expire != tm->single_wheel.current_tick)
          {
            fformat (stdout, "[%d] expired at %d not %d\n",
                     e - tm->test_elts, tm->single_wheel.current_tick,
                     e->expected_to_expire);
          }
     pool_put (tm->test_elts, e);
     }
 }

Definition in file tw_timer_template.h.

Macro Definition Documentation

TW

#define TW

(

a

)

__tw(a,TW_SUFFIX)

Definition at line 31 of file tw_timer_template.h.

TWT

#define TWT

(

a

)

__twt(a,TW_SUFFIX)

Definition at line 27 of file tw_timer_template.h.

Enumeration Type Documentation

tw_ring_index_t

enum tw_ring_index_t

Enumerator
TW_TIMER_RING_FAST	Fast timer ring ID.
TW_TIMER_RING_SLOW	Slow timer ring ID.
TW_TIMER_RING_GLACIER	Glacier ring ID.

Definition at line 162 of file tw_timer_template.h.

Function Documentation

CLIB_PACKED()

typedef CLIB_PACKED

(

struct { u8 timer_id;u32 pool_index;u32 handle;}

)

tw_timer_expire_timers()

u32* TW() tw_timer_expire_timers	(	TWT(tw_timer_wheel) *	tw,
		f64	now
	)

Definition at line 814 of file tw_timer_template.c.

tw_timer_expire_timers_vec()

u32* TW() tw_timer_expire_timers_vec	(	TWT(tw_timer_wheel) *	tw,
		f64	now,
		u32 *	vec
	)

Definition at line 820 of file tw_timer_template.c.

Here is the caller graph for this function:

tw_timer_handle_is_free()

int TW() tw_timer_handle_is_free	(	TWT(tw_timer_wheel) *	tw,
		u32	handle
	)

Definition at line 380 of file tw_timer_template.c.

tw_timer_start()

u32 TW() tw_timer_start	(	TWT(tw_timer_wheel) *	tw,
		u32	user_id,
		u32	timer_id,
		u64	interval
	)

Start a Tw Timer.

Parameters

tw_timer_wheel_t	* tw timer wheel object pointer
u32	user_id user defined timer id, presumably for a tw session
u32	timer_id app-specific timer ID. 4 bits.
u64	interval timer interval in ticks

Returns

handle needed to cancel the timer

Definition at line 296 of file tw_timer_template.c.

Here is the call graph for this function:

Here is the caller graph for this function:

tw_timer_stop()

void TW() tw_timer_stop	(	TWT(tw_timer_wheel) *	tw,
		u32	handle
	)

Stop a tw timer.

Parameters

tw_timer_wheel_t	* tw timer wheel object pointer
u32	handle timer cancellation returned by tw_timer_start

Definition at line 352 of file tw_timer_template.c.

Here is the caller graph for this function:

tw_timer_update()

void TW() tw_timer_update	(	TWT(tw_timer_wheel) *	tw,
		u32	handle,
		u64	interval
	)

Update a tw timer.

Parameters

tw_timer_wheel_t	* tw timer wheel object pointer
u32	handle timer returned by tw_timer_start
u32	interval timer interval in ticks

Definition at line 392 of file tw_timer_template.c.

Here is the call graph for this function:

Here is the caller graph for this function:

tw_timer_wheel_free()

void TW() tw_timer_wheel_free

(

TWT(tw_timer_wheel) *

tw

)

Free a tw timer wheel template instance.

Parameters

tw_timer_wheel_t

* tw timer wheel object pointer

Definition at line 454 of file tw_timer_template.c.

tw_timer_wheel_init()

void TW() tw_timer_wheel_init	(	TWT(tw_timer_wheel) *	tw,
		void *	expired_timer_callback,
		f64	timer_interval_in_seconds,
		u32	max_expirations
	)

Initialize a tw timer wheel template instance.

Parameters

tw_timer_wheel_t	* tw timer wheel object pointer
void	* expired_timer_callback. Passed a u32 * vector of expired timer handles. The callback is optional.
f64	timer_interval_in_seconds

Definition at line 408 of file tw_timer_template.c.

Here is the call graph for this function:

Here is the caller graph for this function: