Timestamp Class Reference

Represents a moment or interval in time. More...

Classes
union	rep_t
	Type of a Timestamp representation. More...

Public Types
enum	{ max_seconds = (seconds_type) 2147483647U , min_seconds = (seconds_type) -2147483648U }
enum	{   nsec_per_sec = 1000000000 , nsec_per_msec = 1000000 , nsec_per_usec = 1000 , usec_per_sec = 1000000 ,   usec_per_msec = 1000 , msec_per_sec = 1000 , subsec_per_sec = nsec_per_sec , subsec_per_msec = subsec_per_sec / msec_per_sec ,   subsec_per_usec = subsec_per_sec / usec_per_sec }
enum	{ NSUBSEC = subsec_per_sec }
typedef int32_t	seconds_type
	Type represents a number of seconds.
typedef int32_t	value_type
	Return type for msecval(), usecval(), and nsecval().
typedef uninitialized_type	uninitialized_t
typedef seconds_type(Timestamp::*	unspecified_bool_type) () const

Public Member Functions
	Timestamp ()
	Construct a zero-valued Timestamp.
	Timestamp (long sec, uint32_t subsec=0)
	Construct a Timestamp of sec seconds plus subsec subseconds.
	Timestamp (int sec, uint32_t subsec=0)
	Timestamp (unsigned long sec, uint32_t subsec=0)
	Timestamp (unsigned sec, uint32_t subsec=0)
	Timestamp (double)
	Create a timestamp measuring d seconds.
	Timestamp (const struct timeval &tv)
	Create a Timestamp measuring tv.
	Timestamp (const struct timespec &ts)
	Create a Timestamp measuring ts.
	Timestamp (const rep_t &rep)
	Construct a Timestamp from its internal representation.
	Timestamp (const uninitialized_t &unused)
	Construct an uninitialized timestamp.
	operator unspecified_bool_type () const
	Return true iff this timestamp is not zero-valued.
bool	is_negative () const
	Test if this Timestamp is negative (< Timestamp(0, 0)).
seconds_type	sec () const
	Return this timestamp's seconds component.
uint32_t	subsec () const
	Return this timestamp's subseconds component.
uint32_t	msec () const
	Return this timestamp's subseconds component, converted to milliseconds.
uint32_t	usec () const
	Return this timestamp's subseconds component, converted to microseconds.
uint32_t	nsec () const
	Return this timestamp's subseconds component, converted to nanoseconds.
void	set_sec (seconds_type sec)
	Set this timestamp's seconds component.
void	set_subsec (uint32_t subsec)
	Set this timestamp's subseconds component.
seconds_type	msec1 () const
	Return this timestamp's interval length, converted to milliseconds.
seconds_type	usec1 () const
	Return this timestamp's interval length, converted to microseconds.
seconds_type	nsec1 () const
	Return this timestamp's interval length, converted to nanoseconds.
struct timeval	timeval () const
	Return a struct timeval that approximates this timestamp.
struct timeval	timeval_ceil () const
	Return the minimum struct timeval >= this timestamp.
struct timespec	timespec () const
	Return a struct timespec with the same value as this timestamp.
int64_t	longval () const
	Return this timestamp's value in subseconds.
void	assignlong (int64_t)
double	doubleval () const
	Return this timestamp's value, converted to a real number.
value_type	msecval () const
	Return this timestamp's interval length in milliseconds.
value_type	usecval () const
	Return this timestamp's interval length in microseconds.
value_type	nsecval () const
	Return this timestamp's interval length in nanoseconds.
Timestamp	msec_ceil () const
	Return the next millisecond-valued timestamp no smaller than *this.
Timestamp	usec_ceil () const
	Return the next microsecond-valued timestamp no smaller than *this.
Timestamp	nsec_ceil () const
	Return the next nanosecond-valued timestamp no smaller than *this.
click_jiffies_t	jiffies () const
	Return the number of jiffies represented by this timestamp.
void	clear ()
	Clear this timestamp.
void	assign (seconds_type sec, uint32_t subsec=0)
void	assign_usec (seconds_type sec, uint32_t usec)
void	assign_nsec (seconds_type sec, uint32_t nsec)
void	assign_now ()
	Set this timestamp to the current system time.
void	assign_recent ()
	Set this timestamp to a recent system time.
void	assign_now_steady ()
	Set this timestamp to the current steady-clock time.
void	assign_recent_steady ()
	Set this timestamp to a recent steady-clock time.
void	assign_now_nouser (bool steady)
	Set this timestamp to the current clock time without calling the user clock if one is set.
String	unparse () const
	Unparse this timestamp into a String.
String	unparse_interval () const
	Unparse this timestamp into a String as an interval.

Static Public Member Functions
static Timestamp	make_jiffies (click_jiffies_t jiffies)
	Return a timestamp representing an interval of jiffies.
static Timestamp	make_jiffies (click_jiffies_difference_t jiffies)
static Timestamp	make_sec (seconds_type sec)
	Return a timestamp representing sec seconds.
static Timestamp	make_msec (seconds_type sec, uint32_t msec)
	Return a timestamp representing sec seconds plus msec milliseconds.
static Timestamp	make_msec (value_type msec)
	Return a timestamp representing msec milliseconds.
static Timestamp	make_usec (seconds_type sec, uint32_t usec)
	Return a timestamp representing sec seconds plus usec microseconds.
static Timestamp	make_usec (value_type usec)
	Return a timestamp representing usec microseconds.
static Timestamp	make_nsec (seconds_type sec, uint32_t nsec)
	Return a timestamp representing sec seconds plus nsec nanoseconds.
static Timestamp	make_nsec (value_type nsec)
	Return a timestamp representing nsec nanoseconds.
static Timestamp	epsilon ()
	Return the smallest nonzero timestamp, Timestamp(0, 1).
static Timestamp	now ()
	Return the current system time.
static Timestamp	recent ()
	Return a recent system time.
static Timestamp	now_steady ()
	Return the current steady-clock time.
static Timestamp	recent_steady ()
	Return a recent steady-clock time.
static uint32_t	msec_to_subsec (uint32_t msec)
	Convert milliseconds to subseconds.
static uint32_t	usec_to_subsec (uint32_t usec)
	Convert microseconds to subseconds.
static uint32_t	nsec_to_subsec (uint32_t nsec)
	Convert nanoseconds to subseconds.
static uint32_t	subsec_to_msec (uint32_t subsec)
	Convert subseconds to milliseconds.
static uint32_t	subsec_to_usec (uint32_t subsec)
	Convert subseconds to microseconds.
static uint32_t	subsec_to_nsec (uint32_t subsec)
	Convert subseconds to nanoseconds.

Related Symbols
(Note that these are not member symbols.)
bool	operator== (const Timestamp &a, const Timestamp &b)
	Compare two timestamps for equality.
bool	operator!= (const Timestamp &a, const Timestamp &b)
	Compare two timestamps for inequality.
bool	operator< (const Timestamp &a, const Timestamp &b)
	Compare two timestamps.
bool	operator<= (const Timestamp &a, const Timestamp &b)
	Compare two timestamps.
bool	operator>= (const Timestamp &a, const Timestamp &b)
	Compare two timestamps.
bool	operator> (const Timestamp &a, const Timestamp &b)
	Compare two timestamps.
StringAccum &	operator<< (StringAccum &sa, const Timestamp &ts)
	Append the unparsed representation of ts to sa.

Detailed Description

Represents a moment or interval in time.

The Click Timestamp class represents both moments in time and intervals in time. In most Click code, Timestamp replaces the Unix "struct timeval" and "struct timespec" structures; for example, Timer expiry times use the Timestamp class. Timestamps may be added, subtracted, and compared using the usual operators.

Timestamp measures time in seconds, and provides access to seconds and "subseconds", or fractions of a second. Click can be configured with either microsecond or nanosecond precision. Thus, one subsecond might equal either one microsecond or one nanosecond. The subsec_per_sec enumeration constant equals the number of subseconds in a second; the timestamp's subsec() value should always lie between 0 and subsec_per_sec - 1. (The –enable-nanotimestamp configuration option enables nanosecond-precision timestamps at user level; kernel modules use the kernel's native timestamp precision, which in later versions of Linux is nanosecond-precision.)

A Timestamp with sec() < 0 is negative. Note that subsec() is always nonnegative. A Timestamp's value always equals (sec() + subsec() / (double) subsec_per_sec); thus, the Timestamp value of -0.1 is represented as sec() == -1, usec() == +900000.

Member Typedef Documentation

seconds_type

typedef int32_t Timestamp::seconds_type

Type represents a number of seconds.

value_type

typedef int32_t Timestamp::value_type

Return type for msecval(), usecval(), and nsecval().

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
max_seconds	Maximum number of seconds representable in a Timestamp.
min_seconds	Minimum number of seconds representable in a Timestamp.

anonymous enum

anonymous enum

Enumerator
subsec_per_sec	Number of subseconds in a second. Can be 1000000 or 1000000000, depending on how Click is compiled.

Constructor & Destructor Documentation

Timestamp() [1/10]

Timestamp::Timestamp ( )

inline

Construct a zero-valued Timestamp.

Timestamp() [2/10]

Timestamp::Timestamp ( long  sec, uint32_t  subsec = 0  )

inlineexplicit

Construct a Timestamp of sec seconds plus subsec subseconds.

Parameters

sec	number of seconds
subsec	number of subseconds (defaults to 0)

The subsec parameter must be between 0 and subsec_per_sec - 1, and the sec parameter must be between min_seconds and max_seconds . Errors are not necessarily checked.

Timestamp() [3/10]

Timestamp::Timestamp ( int  sec, uint32_t  subsec = 0  )

inlineexplicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Timestamp() [4/10]

Timestamp::Timestamp ( unsigned long  sec, uint32_t  subsec = 0  )

inlineexplicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Timestamp() [5/10]

Timestamp::Timestamp ( unsigned  sec, uint32_t  subsec = 0  )

inlineexplicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Timestamp() [6/10]

Timestamp::Timestamp ( double  d )

inlineexplicit

Create a timestamp measuring d seconds.

Timestamp() [7/10]

Timestamp::Timestamp ( const struct timeval &  tv )

inline

Create a Timestamp measuring tv.

Parameters

tv	timeval structure

Timestamp() [8/10]

Timestamp::Timestamp ( const struct timespec &  ts )

inline

Create a Timestamp measuring ts.

Parameters

ts	timespec structure

Timestamp() [9/10]

Timestamp::Timestamp ( const rep_t &  rep )

inline

Construct a Timestamp from its internal representation.

Timestamp() [10/10]

Timestamp::Timestamp ( const uninitialized_t &  unused )

inline

Construct an uninitialized timestamp.

Member Function Documentation

operator unspecified_bool_type()

Timestamp::operator unspecified_bool_type ( ) const

inline

Return true iff this timestamp is not zero-valued.

is_negative()

bool Timestamp::is_negative ( ) const

inline

Test if this Timestamp is negative (< Timestamp(0, 0)).

sec()

Timestamp::seconds_type Timestamp::sec ( ) const

inline

Return this timestamp's seconds component.

subsec()

uint32_t Timestamp::subsec ( ) const

inline

Return this timestamp's subseconds component.

msec()

uint32_t Timestamp::msec ( ) const

inline

Return this timestamp's subseconds component, converted to milliseconds.

usec()

uint32_t Timestamp::usec ( ) const

inline

Return this timestamp's subseconds component, converted to microseconds.

nsec()

uint32_t Timestamp::nsec ( ) const

inline

Return this timestamp's subseconds component, converted to nanoseconds.

set_sec()

void Timestamp::set_sec ( seconds_type  sec )

inline

Set this timestamp's seconds component.

The subseconds component is left unchanged.

set_subsec()

void Timestamp::set_subsec ( uint32_t  subsec )

inline

Set this timestamp's subseconds component.

Parameters

subsec

number of subseconds

The seconds component is left unchanged.

msec1()

Timestamp::seconds_type Timestamp::msec1 ( ) const

inline

Return this timestamp's interval length, converted to milliseconds.

Will overflow on intervals of more than 2147483.647 seconds.

usec1()

Timestamp::seconds_type Timestamp::usec1 ( ) const

inline

Return this timestamp's interval length, converted to microseconds.

Will overflow on intervals of more than 2147.483647 seconds.

nsec1()

Timestamp::seconds_type Timestamp::nsec1 ( ) const

inline

Return this timestamp's interval length, converted to nanoseconds.

Will overflow on intervals of more than 2.147483647 seconds.

timeval()

struct timeval Timestamp::timeval ( ) const

inline

Return a struct timeval that approximates this timestamp.

If Timestamp and struct timeval have the same size and representation, then this operation returns a "const struct timeval &" whose address is the same as this Timestamp. If Timestamps have nanosecond precision, the conversion rounds down, so Timestamp(t.timeval()) <= t.

timeval_ceil()

struct timeval Timestamp::timeval_ceil ( ) const

inline

Return the minimum struct timeval >= this timestamp.

If Timestamp and struct timeval have the same size and representation, then this operation returns a "const struct timeval &" whose address is the same as this Timestamp.

timespec()

struct timespec Timestamp::timespec ( ) const

inline

Return a struct timespec with the same value as this timestamp.

If Timestamp and struct timespec have the same size and representation, then this operation returns a "const struct timespec &" whose address is the same as this Timestamp.

longval()

int64_t Timestamp::longval ( ) const

inline

Return this timestamp's value in subseconds.

doubleval()

double Timestamp::doubleval ( ) const

inline

Return this timestamp's value, converted to a real number.

msecval()

value_type Timestamp::msecval ( ) const

inline

Return this timestamp's interval length in milliseconds.

usecval()

value_type Timestamp::usecval ( ) const

inline

Return this timestamp's interval length in microseconds.

nsecval()

value_type Timestamp::nsecval ( ) const

inline

Return this timestamp's interval length in nanoseconds.

msec_ceil()

Timestamp Timestamp::msec_ceil ( ) const

inline

Return the next millisecond-valued timestamp no smaller than *this.

usec_ceil()

Timestamp Timestamp::usec_ceil ( ) const

inline

Return the next microsecond-valued timestamp no smaller than *this.

nsec_ceil()

Timestamp Timestamp::nsec_ceil ( ) const

inline

Return the next nanosecond-valued timestamp no smaller than *this.

make_jiffies() [1/2]

Timestamp Timestamp::make_jiffies ( click_jiffies_t  jiffies )

inlinestatic

Return a timestamp representing an interval of jiffies.

make_jiffies() [2/2]

Timestamp Timestamp::make_jiffies ( click_jiffies_difference_t  jiffies )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

jiffies()

click_jiffies_t Timestamp::jiffies ( ) const

inline

Return the number of jiffies represented by this timestamp.

make_sec()

static Timestamp Timestamp::make_sec ( seconds_type  sec )

inlinestatic

Return a timestamp representing sec seconds.

make_msec() [1/2]

static Timestamp Timestamp::make_msec ( seconds_type  sec, uint32_t  msec  )

inlinestatic

Return a timestamp representing sec seconds plus msec milliseconds.

Precondition

0 <= msec < 1000

make_msec() [2/2]

static Timestamp Timestamp::make_msec ( value_type  msec )

inlinestatic

Return a timestamp representing msec milliseconds.

make_usec() [1/2]

static Timestamp Timestamp::make_usec ( seconds_type  sec, uint32_t  usec  )

inlinestatic

Return a timestamp representing sec seconds plus usec microseconds.

Precondition

0 <= usec < 1000000

make_usec() [2/2]

static Timestamp Timestamp::make_usec ( value_type  usec )

inlinestatic

Return a timestamp representing usec microseconds.

make_nsec() [1/2]

static Timestamp Timestamp::make_nsec ( seconds_type  sec, uint32_t  nsec  )

inlinestatic

Return a timestamp representing sec seconds plus nsec nanoseconds.

Precondition

0 <= nsec < 1000000000

make_nsec() [2/2]

static Timestamp Timestamp::make_nsec ( value_type  nsec )

inlinestatic

Return a timestamp representing nsec nanoseconds.

epsilon()

static Timestamp Timestamp::epsilon ( )

inlinestatic

Return the smallest nonzero timestamp, Timestamp(0, 1).

clear()

void Timestamp::clear ( )

inline

Clear this timestamp.

assign()

void Timestamp::assign ( seconds_type  sec, uint32_t  subsec = 0  )

inline

Set this timestamp to a seconds-and-subseconds value.

See also

Timestamp(int, int)

assign_usec()

void Timestamp::assign_usec ( seconds_type  sec, uint32_t  usec  )

inline

Assign this timestamp to a seconds-and-microseconds value.

assign_nsec()

void Timestamp::assign_nsec ( seconds_type  sec, uint32_t  nsec  )

inline

Assign this timestamp to a seconds-and-nanoseconds value.

now()

Timestamp Timestamp::now ( )

inlinestatic

Return the current system time.

never

System time is measured in seconds since January 1, 1970 GMT. Produces the most precise timestamp available.

Note

System time can jump forwards or backwards as a result of user actions. For a clock that never moves backwards, see now_steady().

See also

recent(), assign_now(), now_steady()

assign_now()

void Timestamp::assign_now ( )

inline

Set this timestamp to the current system time.

Like "*this = Timestamp::now()".

See also

now(), assign_recent()

recent()

Timestamp Timestamp::recent ( )

inlinestatic

Return a recent system time.

The Timestamp::now() function calculates the current system time, which is relatively expensive. Timestamp::recent() can be faster, but is less precise: it returns a cached copy of a recent system time.

See also

now(), assign_recent()

assign_recent()

void Timestamp::assign_recent ( )

inline

Set this timestamp to a recent system time.

Like "*this = Timestamp::recent()".

See also

recent(), assign_now()

now_steady()

Timestamp Timestamp::now_steady ( )

inlinestatic

Return the current steady-clock time.

The steady clock, often called a monotonic clock, is a system clock that never moves backwards. Steady-clock time is measured in seconds since an undefined start point (often related to the most recent boot). Produces the most precise timestamp available.

Note

Steady-clock times and system times are incomparable, since they have different start points.

See also

recent_steady(), assign_now_steady()

assign_now_steady()

void Timestamp::assign_now_steady ( )

inline

Set this timestamp to the current steady-clock time.

Like "*this = Timestamp::now_steady()".

See also

now_steady()

recent_steady()

Timestamp Timestamp::recent_steady ( )

inlinestatic

Return a recent steady-clock time.

The Timestamp::now_steady() function calculates the current steady-clock time, which is relatively expensive. Timestamp::recent_steady() can be faster, but is less precise: it returns a cached copy of a recent steady-clock time.

See also

now_steady(), assign_recent_steady()

assign_recent_steady()

void Timestamp::assign_recent_steady ( )

inline

Set this timestamp to a recent steady-clock time.

Like "*this = Timestamp::recent_steady()".

See also

recent_steady(), assign_now_steady()

assign_now_nouser()

void Timestamp::assign_now_nouser ( bool  steady )

inline

Set this timestamp to the current clock time without calling the user clock if one is set.

unparse()

String Timestamp::unparse

(

)

const

Unparse this timestamp into a String.

Returns a string formatted like "10.000000", with at least six subsecond digits. (Nanosecond-precision timestamps where the number of nanoseconds is not evenly divisible by 1000 are given nine subsecond digits.)

unparse_interval()

String Timestamp::unparse_interval

(

)

const

Unparse this timestamp into a String as an interval.

Returns a string formatted like "1us" or "1.000002s".

msec_to_subsec()

static uint32_t Timestamp::msec_to_subsec ( uint32_t  msec )

inlinestatic

Convert milliseconds to subseconds.

Subseconds are either microseconds or nanoseconds, depending on configuration options and driver choice.

See also

usec_to_subsec(), nsec_to_subsec(), subsec_to_msec(), subsec_to_usec(), subsec_to_nsec()

usec_to_subsec()

static uint32_t Timestamp::usec_to_subsec ( uint32_t  usec )

inlinestatic

Convert microseconds to subseconds.

nsec_to_subsec()

static uint32_t Timestamp::nsec_to_subsec ( uint32_t  nsec )

inlinestatic

Convert nanoseconds to subseconds.

subsec_to_msec()

static uint32_t Timestamp::subsec_to_msec ( uint32_t  subsec )

inlinestatic

Convert subseconds to milliseconds.

subsec_to_usec()

static uint32_t Timestamp::subsec_to_usec ( uint32_t  subsec )

inlinestatic

Convert subseconds to microseconds.

subsec_to_nsec()

static uint32_t Timestamp::subsec_to_nsec ( uint32_t  subsec )

inlinestatic

Convert subseconds to nanoseconds.

Friends And Related Symbol Documentation

operator==()

bool operator== ( const Timestamp &  a, const Timestamp &  b  )

related

Compare two timestamps for equality.

never

Returns true iff the two operands have the same seconds and subseconds components.

operator!=()

bool operator!= ( const Timestamp &  a, const Timestamp &  b  )

related

Compare two timestamps for inequality.

Returns true iff !(a == b).

operator<()

bool operator< ( const Timestamp &  a, const Timestamp &  b  )

related

Compare two timestamps.

Returns true iff a represents a shorter interval than b, or considered as absolute time, a happened before b.

operator<=()

bool operator<= ( const Timestamp &  a, const Timestamp &  b  )

related

Compare two timestamps.

Returns true iff a measures an interval no larger than b, or considered as absolute time, a happened at or before b.

operator>=()

bool operator>= ( const Timestamp &  a, const Timestamp &  b  )

related

Compare two timestamps.

Returns true iff a measures an interval no shorter than b, or considered as absolute time, a happened at or after b.

operator>()

bool operator> ( const Timestamp &  a, const Timestamp &  b  )

related

Compare two timestamps.

Returns true iff a measures a longer interval than b, or considered as absolute time, a happened after b.

operator<<()

StringAccum & operator<< ( StringAccum &  sa, const Timestamp &  ts  )

related

Append the unparsed representation of ts to sa.

Same as sa << ts.unparse().

---

The documentation for this class was generated from the following files:

• include/click/timestamp.hh
• lib/timestamp.cc