Robot Control Library
Time

Description

sleep and timing functions

All functions are POSIX compliant and should work on any linux system.

Author
James Strawson
Date
1/31/2018

Typedefs

typedef struct timespec timespec
 
typedef struct timeval timeval
 

Functions

void rc_nanosleep (uint64_t ns)
 Sleep in nanoseconds. More...
 
void rc_usleep (unsigned int us)
 Sleep in microseconds. More...
 
uint64_t rc_nanos_since_epoch (void)
 Returns the number of nanoseconds since epoch using system CLOCK_REALTIME. More...
 
uint64_t rc_nanos_since_boot (void)
 Returns the number of nanoseconds since system boot using CLOCK_MONOTONIC. More...
 
uint64_t rc_nanos_thread_time (void)
 Returns the number of nanoseconds from when when the calling thread was started in CPU time. More...
 
uint64_t rc_timespec_to_micros (timespec ts)
 Returns a number of microseconds corresponding to a timespec struct. More...
 
uint64_t rc_timespec_to_millis (timespec ts)
 Returns a number of milliseconds corresponding to a timespec struct. More...
 
uint64_t rc_timeval_to_micros (timeval tv)
 Returns a number of microseconds corresponding to a timeval struct. More...
 
uint64_t rc_timeval_to_millis (timeval tv)
 Returns a number of milliseconds corresponding to a timeval struct. More...
 
timespec rc_timespec_diff (timespec A, timespec B)
 Returns the time difference between two timespec structs as another timespec. More...
 
void rc_timespec_add (timespec *start, double seconds)
 Adds an amount of time in seconds to a timespec struct. More...
 

Function Documentation

◆ rc_nanosleep()

void rc_nanosleep ( uint64_t  ns)

Sleep in nanoseconds.

A wrapper for the normal UNIX nanosleep function which takes a number of nanoseconds instead of a timeval struct. This also handles restarting nanosleep with the remaining time in the event that nanosleep is interrupted by a signal. There is no upper limit on the time requested.

Parameters
[in]nsnanoseconds to sleep

◆ rc_usleep()

void rc_usleep ( unsigned int  us)

Sleep in microseconds.

The traditional usleep function, however common, is deprecated in linux as it uses SIGALARM which interferes with alarm and timer functions. This uses the new POSIX standard nanosleep to accomplish the same thing which further supports sleeping for lengths longer than 1 second. This also handles restarting nanosleep with the remaining time in the event that nanosleep is interrupted by a signal. There is no upper limit on the time requested.

Parameters
[in]usmicroseconds to sleep
Examples:
rc_altitude.c, rc_balance.c, rc_blink.c, rc_calibrate_escs.c, rc_calibrate_mag.c, rc_check_battery.c, rc_dsm_passthrough.c, rc_test_adc.c, rc_test_bmp.c, rc_test_buttons.c, rc_test_complementary_filters.c, rc_test_dmp.c, rc_test_dmp_tap.c, rc_test_dsm.c, rc_test_encoders.c, rc_test_encoders_eqep.c, rc_test_encoders_pru.c, rc_test_escs.c, rc_test_filters.c, rc_test_kalman.c, rc_test_leds.c, rc_test_motors.c, rc_test_mpu.c, and rc_test_servos.c.

◆ rc_nanos_since_epoch()

uint64_t rc_nanos_since_epoch ( void  )

Returns the number of nanoseconds since epoch using system CLOCK_REALTIME.

This function itself takes about 1100ns to complete on a beaglebone at 1ghz under ideal circumstances.

Returns
nanoseconds since epoch
Examples:
rc_test_time.c.

◆ rc_nanos_since_boot()

uint64_t rc_nanos_since_boot ( void  )

Returns the number of nanoseconds since system boot using CLOCK_MONOTONIC.

This function itself takes about 1100ns to complete on a bealgebone at 1ghz under ideal circumstances.

Returns
nanoseconds since system boot
Examples:
rc_test_time.c.

◆ rc_nanos_thread_time()

uint64_t rc_nanos_thread_time ( void  )

Returns the number of nanoseconds from when when the calling thread was started in CPU time.

This uses CLOCK_THREAD_CPUTIME_ID. This time only increments when the processor is working on the calling thread and not when the thread is sleeping. This is usually for timing how long blocks of user-code take to execute. This function itself takes about 2100ns to complete on a beaglebone at 1ghz under ideal circumstances.

Returns
nanoseconds of CPU time since thread started
Examples:
rc_test_time.c.

◆ rc_timespec_to_micros()

uint64_t rc_timespec_to_micros ( timespec  ts)

Returns a number of microseconds corresponding to a timespec struct.

Useful because timespec structs are annoying.

Parameters
[in]tstimespec struct to convert
Returns
time in microseconds

◆ rc_timespec_to_millis()

uint64_t rc_timespec_to_millis ( timespec  ts)

Returns a number of milliseconds corresponding to a timespec struct.

Useful because timespec structs are annoying.

Parameters
[in]tstimespec struct to convert
Returns
time in milliseconds

◆ rc_timeval_to_micros()

uint64_t rc_timeval_to_micros ( timeval  tv)

Returns a number of microseconds corresponding to a timeval struct.

Useful because timeval structs are annoying.

Parameters
[in]tvtimeval struct to convert
Returns
time in microseconds

◆ rc_timeval_to_millis()

uint64_t rc_timeval_to_millis ( timeval  tv)

Returns a number of milliseconds corresponding to a timeval struct.

Useful because timespec structs are annoying.

Parameters
[in]tvtimeval struct to convert
Returns
time in microseconds

◆ rc_timespec_diff()

timespec rc_timespec_diff ( timespec  A,
timespec  B 
)

Returns the time difference between two timespec structs as another timespec.

Convenient for use with nanosleep() function and accurately timed loops. Unlike timespec_sub defined in time.h, rc_timespec_diff does not care which came first, A or B. A positive difference in time is always returned.

Parameters
[in]Atimespec struct
[in]Btimespec struct
Returns
timespec struct of the difference, always positive

◆ rc_timespec_add()

void rc_timespec_add ( timespec start,
double  seconds 
)

Adds an amount of time in seconds to a timespec struct.

The time added is a double-precision floating point value to make respresenting fractions of a second easier. The timespec is passed as a pointer so it can be modified in place. Seconds may be negative.

Parameters
startThe start timspec, modified in place
[in]secondsThe seconds