FD.io VPP  v19.08.2-294-g37e99c22d
Vector Packet Processing
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

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 813 of file tw_timer_template.c.

+ Here is the call graph for this function:

◆ tw_timer_expire_timers_vec()

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

Definition at line 818 of file tw_timer_template.c.

+ Here is the call 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 379 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
u32user_id user defined timer id, presumably for a tw session
u32timer_id app-specific timer ID. 4 bits.
u64interval 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
u32handle timer cancellation returned by tw_timer_start

Definition at line 352 of file tw_timer_template.c.

+ Here is the call 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
u32handle timer returned by tw_timer_start
u32interval timer interval in ticks

Definition at line 390 of file tw_timer_template.c.

+ Here is the call 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 453 of file tw_timer_template.c.

+ Here is the call graph for this function:

◆ 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.
f64timer_interval_in_seconds

Definition at line 407 of file tw_timer_template.c.

+ Here is the call graph for this function: