rcutils  master
C API providing common utilities and data structures.
Macros | Typedefs | Functions
time.h File Reference
#include <stdint.h>
#include "rcutils/macros.h"
#include "rcutils/types.h"
#include "rcutils/visibility_control.h"

Go to the source code of this file.

Macros

#define RCUTILS_S_TO_NS(seconds)   (seconds * (1000 * 1000 * 1000))
 Convenience macro to convert seconds to nanoseconds. More...
 
#define RCUTILS_MS_TO_NS(milliseconds)   (milliseconds * (1000 * 1000))
 Convenience macro to convert milliseconds to nanoseconds. More...
 
#define RCUTILS_US_TO_NS(microseconds)   (microseconds * 1000)
 Convenience macro to convert microseconds to nanoseconds. More...
 
#define RCUTILS_NS_TO_S(nanoseconds)   (nanoseconds / (1000 * 1000 * 1000))
 Convenience macro to convert nanoseconds to seconds. More...
 
#define RCUTILS_NS_TO_MS(nanoseconds)   (nanoseconds / (1000 * 1000))
 Convenience macro to convert nanoseconds to milliseconds. More...
 
#define RCUTILS_NS_TO_US(nanoseconds)   (nanoseconds / 1000)
 Convenience macro to convert nanoseconds to microseconds. More...
 

Typedefs

typedef int64_t rcutils_time_point_value_t
 A single point in time, measured in nanoseconds since the Unix epoch. More...
 
typedef int64_t rcutils_duration_value_t
 A duration of time, measured in nanoseconds. More...
 

Functions

rcutils_ret_t rcutils_system_time_now (rcutils_time_point_value_t *now)
 
rcutils_ret_t rcutils_steady_time_now (rcutils_time_point_value_t *now)
 Retrieve the current time as a rcutils_time_point_value_t object. More...
 
rcutils_ret_t rcutils_time_point_value_as_nanoseconds_string (const rcutils_time_point_value_t *time_point, char *str, size_t str_size)
 Return a time point as nanoseconds in a string. More...
 
rcutils_ret_t rcutils_time_point_value_as_seconds_string (const rcutils_time_point_value_t *time_point, char *str, size_t str_size)
 Return a time point as floating point seconds in a string. More...
 

Macro Definition Documentation

◆ RCUTILS_S_TO_NS

#define RCUTILS_S_TO_NS (   seconds)    (seconds * (1000 * 1000 * 1000))

Convenience macro to convert seconds to nanoseconds.

◆ RCUTILS_MS_TO_NS

#define RCUTILS_MS_TO_NS (   milliseconds)    (milliseconds * (1000 * 1000))

Convenience macro to convert milliseconds to nanoseconds.

◆ RCUTILS_US_TO_NS

#define RCUTILS_US_TO_NS (   microseconds)    (microseconds * 1000)

Convenience macro to convert microseconds to nanoseconds.

◆ RCUTILS_NS_TO_S

#define RCUTILS_NS_TO_S (   nanoseconds)    (nanoseconds / (1000 * 1000 * 1000))

Convenience macro to convert nanoseconds to seconds.

◆ RCUTILS_NS_TO_MS

#define RCUTILS_NS_TO_MS (   nanoseconds)    (nanoseconds / (1000 * 1000))

Convenience macro to convert nanoseconds to milliseconds.

◆ RCUTILS_NS_TO_US

#define RCUTILS_NS_TO_US (   nanoseconds)    (nanoseconds / 1000)

Convenience macro to convert nanoseconds to microseconds.

Typedef Documentation

◆ rcutils_time_point_value_t

typedef int64_t rcutils_time_point_value_t

A single point in time, measured in nanoseconds since the Unix epoch.

◆ rcutils_duration_value_t

typedef int64_t rcutils_duration_value_t

A duration of time, measured in nanoseconds.

Function Documentation

◆ rcutils_system_time_now()

rcutils_ret_t rcutils_system_time_now ( rcutils_time_point_value_t now)

This function returns the time from a system clock. The closest equivalent would be to std::chrono::system_clock::now();

The resolution (e.g. nanoseconds vs microseconds) is not guaranteed.

The now argument must point to an allocated rcutils_time_point_value_t object, as the result is copied into this variable.


Attribute Adherence —
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[out]nowa datafield in which the current time is stored
Returns
RCUTILS_RET_OK if the current time was successfully obtained, or
RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCUTILS_RET_ERROR if an unspecified error occur.

◆ rcutils_steady_time_now()

rcutils_ret_t rcutils_steady_time_now ( rcutils_time_point_value_t now)

Retrieve the current time as a rcutils_time_point_value_t object.

This function returns the time from a monotonically increasing clock. The closest equivalent would be to std::chrono::steady_clock::now();

The resolution (e.g. nanoseconds vs microseconds) is not guaranteed.

The now argument must point to an allocated rcutils_time_point_value_t object, as the result is copied into this variable.


Attribute Adherence —
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[out]nowa struct in which the current time is stored
Returns
RCUTILS_RET_OK if the current time was successfully obtained, or
RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCUTILS_RET_ERROR if an unspecified error occur.

◆ rcutils_time_point_value_as_nanoseconds_string()

rcutils_ret_t rcutils_time_point_value_as_nanoseconds_string ( const rcutils_time_point_value_t time_point,
char *  str,
size_t  str_size 
)

Return a time point as nanoseconds in a string.

The number is always fixed width, with left padding zeros up to the maximum number of digits the time point can represent. Right now that is 19 digits (so 19 characters) for a signed 64-bit integer. Negative values will have a leading -, so they will be one character longer than the positive values.

The recommended minimum size of the input string is 32 characters, but 21 ( or - for sign, 19 digits, null terminator) should be sufficiently large for both positive and negative values. If the given string is not large enough, the result will be truncated. If you need a string with variable width, using snprintf() directly is recommended.


Attribute Adherence —
Allocates Memory No [1]
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes

[1] if snprintf() does not allocate additional memory internally

Parameters
[in]time_pointthe time to be made into a string
[out]strthe output string in which it is stored
[in]str_sizethe size of the output string
Returns
RCUTILS_RET_OK if successful (even if truncated), or
RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCUTILS_RET_ERROR if an unspecified error occur.

◆ rcutils_time_point_value_as_seconds_string()

rcutils_ret_t rcutils_time_point_value_as_seconds_string ( const rcutils_time_point_value_t time_point,
char *  str,
size_t  str_size 
)

Return a time point as floating point seconds in a string.

The number is always fixed width, with left padding zeros up to the maximum number of digits for the mantissa that the time point can represent and a characteristic (fractional-part) with a fixed width of 9 digits. Right now that means the mantissa is always 10 digits to add up to 19 total for the signed 64-bit time point type. Negative values will have a leading -, so they will be one character longer then positive values.

The recommended minimum size of the input string is 32 characters, but 22 ( or - for sign, 19 digits, decimal point, null terminator) should be sufficient for now. If the given string is not large enough, the result will be truncated.


Attribute Adherence —
Allocates Memory No [1]
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes

[1] if snprintf() does not allocate additional memory internally

Parameters
[in]time_pointthe time to be made into a string
[out]strthe output string in which it is stored
[in]str_sizethe size of the output string
Returns
RCUTILS_RET_OK if successful (even if truncated), or
RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCUTILS_RET_ERROR if an unspecified error occur.