jtimers.h File Reference

Juniper hierarchical timer functions. More...


Typedefs

typedef jtimer_ jtimer
 Defines a type for a timer.
typedef jtimer_context_ jtimer_context
 Defines a type for a timer context.
typedef void(* jtimer_callback_func )(jtimer *timer, void *param)
 Defines the timer callback function type.
typedef void(* jtimer_assert_func )(const char *)
 Defines the assert function type.

Functions

jtimer_contextjtimer_init (evContext ctx, jtimer_assert_func assert_func)
 Creates the timer context and links it to the event library context given.
jtimerjtimer_create_leaf (jtimer_context *context, jtimer *parent, jtimer_callback_func func, void *param)
 Creates a leaf timer linked to the context block.
jtimerjtimer_create_parent (jtimer_context *context, jtimer *parent)
 Creates a parent timer linked to the context block.
void jtimer_efficient_jitter (jtimer *timer, u_int efficient)
 Enables or disables efficient jittering of a timer.
void jtimer_destroy (jtimer *timer)
 Destroys a timer.
void jtimer_stop (jtimer *timer)
 Stops a timer.
void jtimer_start_oneshot (jtimer *timer, u_long delay, u_long jitter_pct)
 Start a one-shot timer.
void jtimer_start_oneshot_precise (jtimer *timer, struct timespec *delay, u_long jitter_pct)
 A more precise version of jtimer_start_oneshot().
void jtimer_start_interval (jtimer *timer, u_long interval, u_long jitter_pct)
 Starts an interval timer.
void jtimer_start_interval_precise (jtimer *timer, struct timespec *delay, u_long jitter_pct)
 A more precise version of jtimer_start_interval().
void jtimer_start_autoparent_oneshot (jtimer *timer, u_long delay, u_long jitter_pct)
 Start an autoparent one-shot timer.
void jtimer_start_autoparent_oneshot_precise (jtimer *timer, struct timespec *delay, u_long jitter_pct)
 A more precise version of jtimer_start_autoparent_oneshot().
void jtimer_start_autoparent_interval (jtimer *timer, u_long interval, u_long jitter_pct)
 Starts an autoparent interval timer.
void jtimer_start_autoparent_interval_precise (jtimer *timer, struct timespec *delay, u_long jitter_pct)
 A more precise version of jtimer_start_autoparent_interval().
u_long jtimer_time_remaining (jtimer *timer)
 Determines how many seconds are remaining on the timer.
void jtimer_time_remaining_precise (jtimer *timer, struct timespec *time_left)
 A more precise version of jtimer_time_remaining().
u_int jtimer_expired (jtimer *timer)
 Determines if a timer has expired.
u_int jtimer_running (jtimer *timer)
 Determines if a timer is running.
void jtimer_smear_children (jtimer *timer)
 Smears the expiriation times of the children of the specified parent timer.


Detailed Description

Juniper hierarchical timer functions.

This code provides an interface between the event library and the hierarchical timer code, which is now shared between libjuniper, the microkernel, and rpd. This not only provides the timer hierarchy, but puts a sane interface in front of the event library timer code, which is fairly hideous.

Hierarchical timers exist in a hierarchy, strangely enough. Leaf timers are those that are actually started and expire. Leaf timers may be grouped together under a parent timer; the parent timer assumes the expiration time of the earliest leaf timer. Parent timers can recursively have their own parent timers, allowing large numbers of timers to be managed.

None of this complexity is required; at the most minimal level, one or more leaf timers can be created with no hierarchy (actually, there is an ultimate root timer that is managed behind the scenes).

The caller first must create a timer context with jtimer_init(). This links the timer system to the event library and returns an opaque context block that is used when creating timers.

Timers are then created using jtimer_create_leaf() and jtimer_create_parent(). These functions return a pointer to an opaque timer block that represents the timer.

Only leaf timers may be started. They are started with the various jtimer_start_xxx() routines. When a timer expires, the callback routine that was referenced when the timer was created is called. Oneshot timers are stopped at this point; interval timers automatically restart with their given interval. A timer may be stopped prior to expiration by calling jtimer_stop().

When a timer is no longer needed, it must be disposed of by calling jtimer_destroy().

Autoparent timers are also supported. When a leaf timer is started with one of the autoparent routines, it is grouped under an internally-created parent timer with all other leaf timers having the same interval and jitter values. This can vastly improve scaling when lots of timers are in use and the application doesn't want to manage its own parent timers. Autoparent leaf timers are started with the jtimer_autoparent_start_xxx() routines.

More efficient jittered timers can be created by calling jtimer_efficient_jitter(). Normal jittered timers are calculated without regard to other timers; the cost of starting one may be high if there are many sibling timers. When efficient jittering is enabled for a timer, the amount of jitter applied is sensitive to the expiration time of the sibling timers; the timer is set to expire after all other siblings, if this is possible without exceeding the nominal interval. This means that the amount of jitter applied for a particular timer start may be small or nonexistent if there are many other siblings. This is ideally combined with autoparent timers, since this will guarantee O(1) insertion in all cases.


Typedef Documentation

typedef struct jtimer_context_ jtimer_context
 

Defines a type for a timer context.

Timer context


Function Documentation

jtimer* jtimer_create_leaf jtimer_context context,
jtimer parent,
jtimer_callback_func  func,
void *  param
 

Creates a leaf timer linked to the context block.

parent is a pointer to the parent timer of this timer, or NULL if there is no parent (thus the hierarchy must be created from the root outward).

The timer is stopped when it is first created. When the timer expires, the function func is called with param passed to it.

Parameters:
[in] context Pointer to a timer context, as returned by jtimer_init().
[in] parent Pointer to the parent for this timer
[in] func Function to call when the timer expires
[in] param Parameter to pass to the callback function func when the timer expires
Returns:
A pointer to a new leaf timer; NULL on failure.

jtimer* jtimer_create_parent jtimer_context context,
jtimer parent
 

Creates a parent timer linked to the context block.

The parent is a pointer to the parent of this timer (or NULL if there is no parent).

Parameters:
[in] context Pointer to a timer context, as returned by jtimer_init().
[in] parent Pointer to the parent for this timer
Returns:
A pointer to a new parent jtimer; NULL on failure.

void jtimer_destroy jtimer timer  ) 
 

Destroys a timer.

If the timer is running, it is first stopped.

If the timer being destroyed is a parent timer, all of its children must have been destroyed first (thus the hierarchy is destroyed from the leaves inward).

Parameters:
[in] timer Pointer to a jtimer

void jtimer_efficient_jitter jtimer timer,
u_int  efficient
 

Enables or disables efficient jittering of a timer.

Parameters:
[in] timer Pointer to a jtimer
[in] efficient nonzero if we want efficient jittering, zero if not

u_int jtimer_expired jtimer timer  ) 
 

Determines if a timer has expired.

This function returns a value indicating whether the timer has expired.

Parameters:
[in] timer Pointer to a timer
Returns:
1 if the timer has expired (but not yet been processed); 0 otherwise

jtimer_context* jtimer_init evContext  ctx,
jtimer_assert_func  assert_func
 

Creates the timer context and links it to the event library context given.

If assert_func is non-NULL, it will be called in the event of an assertion failure within the timer code. It is strongly recommended that this callback be supplied.

Parameters:
[in] ctx Event library context
[in] assert_func Function to call in the event of an assertion failure
Returns:
A pointer to a timer context, or NULL on failure.

u_int jtimer_running jtimer timer  ) 
 

Determines if a timer is running.

This function returns a value indicating whether or not the timer is running.

Parameters:
[in] timer Pointer to a timer
Returns:
1 if the timer is running; 0 otherwise

void jtimer_smear_children jtimer timer  ) 
 

Smears the expiriation times of the children of the specified parent timer.

Given a list of sibling leaf timers, this function attempts to space the timers evenly to expire between now and the latest time found on the list.

There are two rules that are followed:

1) Timer expiration order stays the same 2) Timers may be set to expire sooner than before, but never later

It is unlikely that we will be able to evenly space all of the timers, since we will eventually hit a timer that expires earlier than the desired expiration time (as determined by this function).

This function attempts to correct for this by readjusting the expiration interval when it encounters a timer that expires earlier than desired.

The function recalculates the interval by trying to smear between that time and the final expiration time on the list.

All of the children must be leaf timers.

Parameters:
[in] timer Pointer to a jtimer

void jtimer_start_autoparent_interval jtimer timer,
u_long  interval,
u_long  jitter_pct
 

Starts an autoparent interval timer.

This function starts a timer that will expire repeatedly until it is stopped.

Parameters:
[in] timer Pointer to a jtimer
[in] interval Timer expiration interval
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_autoparent_interval_precise()

void jtimer_start_autoparent_interval_precise jtimer timer,
struct timespec *  delay,
u_long  jitter_pct
 

A more precise version of jtimer_start_autoparent_interval().

This function is the same as jtimer_start_autoparent_interval(), except that the interval is expressed precisely (in seconds and nanoseconds).

Parameters:
[in] timer Pointer to a jtimer
[in] delay Timer interval
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_autoparent_interval()

void jtimer_start_autoparent_oneshot jtimer timer,
u_long  delay,
u_long  jitter_pct
 

Start an autoparent one-shot timer.

After delay seconds, the timer will expire.

A random amount of time, from zero to jitter_pct percent of the delay is subtracted from the delay (so a jitter percentage of zero will expire after the exact delay).

If a timer is already running, starting it again will cause it to be freshly restarted (so deadman timers can be created simply by doing another start prior to each expiration).

Note that the jitter is done precisely and is not truncated to integer seconds.

Parameters:
[in] timer Pointer to a jtimer
[in] delay The number of seconds to delay before timer expiration
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_autoparent_oneshot_precise

void jtimer_start_autoparent_oneshot_precise jtimer timer,
struct timespec *  delay,
u_long  jitter_pct
 

A more precise version of jtimer_start_autoparent_oneshot().

This function is the same as jtimer_start_autoparent_oneshot(), except that the delay is expressed precisely (in seconds and nanoseconds).

Parameters:
[in] timer Pointer to a jtimer
[in] delay Timer interval
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_autoparent_oneshot()

void jtimer_start_interval jtimer timer,
u_long  interval,
u_long  jitter_pct
 

Starts an interval timer.

This function starts a timer that will expire repeatedly until it is stopped.

Parameters:
[in] timer Pointer to a jtimer
[in] interval Timer expiration interval
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_interval_precise()

void jtimer_start_interval_precise jtimer timer,
struct timespec *  delay,
u_long  jitter_pct
 

A more precise version of jtimer_start_interval().

This function is the same as jtimer_start_interval(), except that the interval is expressed precisely (in seconds and nanoseconds).

Parameters:
[in] timer Pointer to a jtimer
[in] delay Timer interval
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_interval()

void jtimer_start_oneshot jtimer timer,
u_long  delay,
u_long  jitter_pct
 

Start a one-shot timer.

After delay seconds, the timer will expire.

A random amount of time, from zero to jitter_pct percent of the delay is subtracted from the delay (so a jitter percentage of zero will expire after the exact delay).

If a timer is already running, starting it again will cause it to be freshly restarted (so deadman timers can be created simply by doing another start prior to each expiration).

Note that the jitter is done precisely and is not truncated to integer seconds.

Parameters:
[in] timer Pointer to a jtimer
[in] delay The number of seconds to delay before timer expiration
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_oneshot_precise

void jtimer_start_oneshot_precise jtimer timer,
struct timespec *  delay,
u_long  jitter_pct
 

A more precise version of jtimer_start_oneshot().

This function is the same as jtimer_start_oneshot(), except that the delay is expressed precisely (in seconds and nanoseconds).

Parameters:
[in] timer Pointer to a jtimer
[in] delay Timer interval
[in] jitter_pct Percentage of jitter to randomly add or subtract from the timer
See also:
jtimer_start_oneshot()

void jtimer_stop jtimer timer  ) 
 

Stops a timer.

The timer is guaranteed not to expire (there are no race conditions possible). If the timer is a parent timer, all of the timers that are children (and grandchildren, etc.) to this timer are stopped.

Parameters:
[in] timer Pointer to a jtimer

u_long jtimer_time_remaining jtimer timer  ) 
 

Determines how many seconds are remaining on the timer.

This function returns the number of seconds remaining until the timer expires.

Parameters:
[in] timer Pointer to a jtimer
Returns:
The number of seconds left before the timer expires.
See also:
jtimer_time_remaining_precise()

void jtimer_time_remaining_precise jtimer timer,
struct timespec *  time_left
 

A more precise version of jtimer_time_remaining().

This function is the same as jtimer_time_remaining(), except that the amount of time left is expressed precisely (in seconds and nanoseconds).

The remaining time is returned in the timespec structure passed in time_left.

Parameters:
[in] timer Pointer to a timer
[in] time_left Pointer to a timespec structure to receive the time remaining.
See also:
jtimer_time_remaining()


2007-2009 Juniper Networks, Inc. All rights reserved. The information contained herein is confidential information of Juniper Networks, Inc., and may not be used, disclosed, distributed, modified, or copied without the prior written consent of Juniper Networks, Inc. in an express license. This information is subject to change by Juniper Networks, Inc. Juniper Networks, the Juniper Networks logo, and JUNOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
Generated on Sun May 30 20:24:32 2010 for libjuniper by Doxygen 1.4.5