rcl  master
C API providing common ROS client library functionality.
time.h
1 // Copyright 2015 Open Source Robotics Foundation, Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef RCL__TIME_H_
16 #define RCL__TIME_H_
17 
18 #ifdef __cplusplus
19 extern "C"
20 {
21 #endif
22 
23 #include "rcl/allocator.h"
24 #include "rcl/macros.h"
25 #include "rcl/types.h"
26 #include "rcl/visibility_control.h"
27 #include "rcutils/time.h"
28 
30 #define RCL_S_TO_NS RCUTILS_S_TO_NS
31 #define RCL_MS_TO_NS RCUTILS_MS_TO_NS
33 #define RCL_US_TO_NS RCUTILS_US_TO_NS
35 
37 #define RCL_NS_TO_S RCUTILS_NS_TO_S
38 #define RCL_NS_TO_MS RCUTILS_NS_TO_MS
40 #define RCL_NS_TO_US RCUTILS_NS_TO_US
42 
44 typedef rcutils_time_point_value_t rcl_time_point_value_t;
46 typedef rcutils_duration_value_t rcl_duration_value_t;
47 
49 
59 typedef enum rcl_clock_type_t
60 {
61  RCL_CLOCK_UNINITIALIZED = 0,
62  RCL_ROS_TIME,
63  RCL_SYSTEM_TIME,
64  RCL_STEADY_TIME
65 } rcl_clock_type_t;
66 
68 typedef struct rcl_duration_t
69 {
71  rcl_duration_value_t nanoseconds;
73 
75 typedef enum rcl_clock_change_t
76 {
78  RCL_ROS_TIME_NO_CHANGE = 1,
80  RCL_ROS_TIME_ACTIVATED = 2,
82  RCL_ROS_TIME_DEACTIVATED = 3,
84  RCL_SYSTEM_TIME_NO_CHANGE = 4
85 } rcl_clock_change_t;
86 
88 typedef struct rcl_time_jump_t
89 {
91  rcl_clock_change_t clock_change;
95 
101 typedef void (* rcl_jump_callback_t)(
102  const struct rcl_time_jump_t * time_jump,
103  bool before_jump,
104  void * user_data);
105 
107 typedef struct rcl_jump_threshold_t
108 {
118 
121 {
123  rcl_jump_callback_t callback;
127  void * user_data;
129 
131 typedef struct rcl_clock_t
132 {
134  enum rcl_clock_type_t type;
140  rcl_ret_t (* get_now)(void * data, rcl_time_point_value_t * now);
141  // void (*set_now) (rcl_time_point_value_t);
143  void * data;
146 } rcl_clock_t;
147 
149 typedef struct rcl_time_point_t
150 {
152  rcl_time_point_value_t nanoseconds;
154  rcl_clock_type_t clock_type;
156 
157 // typedef struct rcl_rate_t
158 // {
159 // rcl_time_point_value_t trigger_time;
160 // int64_t period;
161 // rcl_clock_type_t clock;;
162 // } rcl_rate_t;
163 // TODO(tfoote) integrate rate and timer implementations
164 
166 
183 RCL_PUBLIC
184 RCL_WARN_UNUSED
185 bool
186 rcl_clock_valid(rcl_clock_t * clock);
187 
189 
211 RCL_PUBLIC
212 RCL_WARN_UNUSED
213 rcl_ret_t
214 rcl_clock_init(
215  enum rcl_clock_type_t clock_type, rcl_clock_t * clock,
216  rcl_allocator_t * allocator);
217 
219 
246 RCL_PUBLIC
247 RCL_WARN_UNUSED
248 rcl_ret_t
249 rcl_clock_fini(
250  rcl_clock_t * clock);
251 
253 
275 RCL_PUBLIC
276 RCL_WARN_UNUSED
277 rcl_ret_t
278 rcl_ros_clock_init(
279  rcl_clock_t * clock,
280  rcl_allocator_t * allocator);
281 
283 
308 RCL_PUBLIC
309 RCL_WARN_UNUSED
310 rcl_ret_t
311 rcl_ros_clock_fini(
312  rcl_clock_t * clock);
313 
315 
336 RCL_PUBLIC
337 RCL_WARN_UNUSED
338 rcl_ret_t
339 rcl_steady_clock_init(
340  rcl_clock_t * clock,
341  rcl_allocator_t * allocator);
342 
344 
371 RCL_PUBLIC
372 RCL_WARN_UNUSED
373 rcl_ret_t
374 rcl_steady_clock_fini(
375  rcl_clock_t * clock);
376 
378 
402 RCL_PUBLIC
403 RCL_WARN_UNUSED
404 rcl_ret_t
405 rcl_system_clock_init(
406  rcl_clock_t * clock,
407  rcl_allocator_t * allocator);
408 
410 
436 RCL_PUBLIC
437 RCL_WARN_UNUSED
438 rcl_ret_t
439 rcl_system_clock_fini(
440  rcl_clock_t * clock);
441 
443 
466 RCL_PUBLIC
467 RCL_WARN_UNUSED
468 rcl_ret_t
469 rcl_difference_times(
470  rcl_time_point_t * start, rcl_time_point_t * finish, rcl_duration_t * delta);
471 
473 
493 RCL_PUBLIC
494 RCL_WARN_UNUSED
495 rcl_ret_t
496 rcl_clock_get_now(rcl_clock_t * clock, rcl_time_point_value_t * time_point_value);
497 
498 
500 
525 RCL_PUBLIC
526 RCL_WARN_UNUSED
527 rcl_ret_t
528 rcl_enable_ros_time_override(rcl_clock_t * clock);
529 
531 
556 RCL_PUBLIC
557 RCL_WARN_UNUSED
558 rcl_ret_t
559 rcl_disable_ros_time_override(rcl_clock_t * clock);
560 
561 
563 
587 RCL_PUBLIC
588 RCL_WARN_UNUSED
589 rcl_ret_t
590 rcl_is_enabled_ros_time_override(
591  rcl_clock_t * clock, bool * is_enabled);
592 
594 
621 RCL_PUBLIC
622 RCL_WARN_UNUSED
623 rcl_ret_t
624 rcl_set_ros_time_override(
625  rcl_clock_t * clock, rcl_time_point_value_t time_value);
626 
628 
659 RCL_PUBLIC
660 RCL_WARN_UNUSED
661 rcl_ret_t
662 rcl_clock_add_jump_callback(
663  rcl_clock_t * clock, rcl_jump_threshold_t threshold, rcl_jump_callback_t callback,
664  void * user_data);
665 
667 
692 RCL_PUBLIC
693 RCL_WARN_UNUSED
694 rcl_ret_t
695 rcl_clock_remove_jump_callback(
696  rcl_clock_t * clock, rcl_jump_callback_t callback, void * user_data);
697 
698 #ifdef __cplusplus
699 }
700 #endif
701 
702 #endif // RCL__TIME_H_
rcutils_duration_value_t
int64_t rcutils_duration_value_t
rcl_clock_t::jump_callbacks
rcl_jump_callback_info_t * jump_callbacks
An array of added jump callbacks.
Definition: time.h:136
rcl_clock_t::type
enum rcl_clock_type_t type
Clock type.
Definition: time.h:134
rcl_time_point_t::nanoseconds
rcl_time_point_value_t nanoseconds
Nanoseconds of the point in time.
Definition: time.h:152
rcl_time_jump_t::clock_change
rcl_clock_change_t clock_change
Indicate whether or not the source of time changed.
Definition: time.h:91
time.h
rcl_duration_t::nanoseconds
rcl_duration_value_t nanoseconds
Duration in nanoseconds and its source.
Definition: time.h:71
rcl_clock_t::data
void * data
Clock storage.
Definition: time.h:143
rcl_jump_callback_info_t::callback
rcl_jump_callback_t callback
Callback to fucntion.
Definition: time.h:123
rcl_time_jump_t
Struct to describe a jump in time.
Definition: time.h:88
rcl_jump_threshold_t::min_backward
rcl_duration_t min_backward
Definition: time.h:116
rcl_jump_callback_info_t::threshold
rcl_jump_threshold_t threshold
Threshold to decide when to call the callback.
Definition: time.h:125
rcl_clock_t::get_now
rcl_ret_t(* get_now)(void *data, rcl_time_point_value_t *now)
Pointer to get_now function.
Definition: time.h:140
rcl_time_point_t
A single point in time, measured in nanoseconds, the reference point is based on the source.
Definition: time.h:149
rcl_jump_threshold_t
Describe the prerequisites for calling a time jump callback.
Definition: time.h:107
rcl_time_point_t::clock_type
rcl_clock_type_t clock_type
Clock type of the point in time.
Definition: time.h:154
rcutils_time_point_value_t
int64_t rcutils_time_point_value_t
rcl_jump_threshold_t::on_clock_change
bool on_clock_change
True to call callback when the clock type changes.
Definition: time.h:110
rcl_clock_t
Encapsulation of a time source.
Definition: time.h:131
rcl_clock_t::allocator
rcl_allocator_t allocator
Custom allocator used for internal allocations.
Definition: time.h:145
rcl_jump_callback_info_t::user_data
void * user_data
Pointer passed to the callback.
Definition: time.h:127
rcutils_allocator_t
rcl_time_jump_t::delta
rcl_duration_t delta
The new time minus the last time before the jump.
Definition: time.h:93
rcl_jump_threshold_t::min_forward
rcl_duration_t min_forward
Definition: time.h:113
rcl_clock_t::num_jump_callbacks
size_t num_jump_callbacks
Number of callbacks in jump_callbacks.
Definition: time.h:138
rcl_jump_callback_info_t
Struct to describe an added callback.
Definition: time.h:120
rcl_duration_t
A duration of time, measured in nanoseconds and its source.
Definition: time.h:68