ROS 2 rclcpp + rcl - jazzy  jazzy
ROS 2 C++ Client Library with ROS Client Library
timer.h
Go to the documentation of this file.
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 
16 
17 #ifndef RCL__TIMER_H_
18 #define RCL__TIMER_H_
19 
20 #ifdef __cplusplus
21 extern "C"
22 {
23 #endif
24 
25 #include <stdbool.h>
26 
27 #include "rcl/allocator.h"
28 #include "rcl/context.h"
29 #include "rcl/event_callback.h"
30 #include "rcl/guard_condition.h"
31 #include "rcl/macros.h"
32 #include "rcl/time.h"
33 #include "rcl/types.h"
34 #include "rcutils/logging_macros.h"
35 #include "rmw/rmw.h"
36 
37 typedef struct rcl_timer_impl_s rcl_timer_impl_t;
38 
40 typedef struct rcl_timer_s
41 {
43  rcl_timer_impl_t * impl;
44 } rcl_timer_t;
45 
47 typedef struct rcl_timer_on_reset_callback_data_s
48 {
49  rcl_event_callback_t on_reset_callback;
50  const void * user_data;
51  size_t reset_counter;
52 } rcl_timer_on_reset_callback_data_t;
53 
55 typedef struct rcl_timer_call_info_s
56 {
57  rcl_time_point_value_t expected_call_time;
58  rcl_time_point_value_t actual_call_time;
59 } rcl_timer_call_info_t;
60 
62 
74 typedef void (* rcl_timer_callback_t)(rcl_timer_t *, int64_t);
75 
77 RCL_PUBLIC
78 RCL_WARN_UNUSED
79 rcl_timer_t
80 rcl_get_zero_initialized_timer(void);
81 
83 
169 RCL_PUBLIC
170 RCL_WARN_UNUSED
171 rcl_ret_t
172 rcl_timer_init2(
173  rcl_timer_t * timer,
174  rcl_clock_t * clock,
175  rcl_context_t * context,
176  int64_t period,
177  const rcl_timer_callback_t callback,
178  rcl_allocator_t allocator,
179  bool autostart);
180 
185 RCL_PUBLIC
186 RCUTILS_DEPRECATED_WITH_MSG("Call rcl_timer_init2 instead")
187 rcl_ret_t
188 rcl_timer_init(
189  rcl_timer_t * timer,
190  rcl_clock_t * clock,
191  rcl_context_t * context,
192  int64_t period,
193  const rcl_timer_callback_t callback,
194  rcl_allocator_t allocator);
195 
197 
222 RCL_PUBLIC
223 RCL_WARN_UNUSED
224 rcl_ret_t
225 rcl_timer_fini(rcl_timer_t * timer);
226 
228 
266 RCL_PUBLIC
267 RCL_WARN_UNUSED
268 rcl_ret_t
269 rcl_timer_call(rcl_timer_t * timer);
270 
272 
294 RCL_PUBLIC
295 RCL_WARN_UNUSED
296 rcl_ret_t
297 rcl_timer_call_with_info(rcl_timer_t * timer, rcl_timer_call_info_t * call_info);
298 
300 
319 RCL_PUBLIC
320 RCL_WARN_UNUSED
321 rcl_ret_t
322 rcl_timer_clock(const rcl_timer_t * timer, rcl_clock_t ** clock);
323 
325 
349 RCL_PUBLIC
350 RCL_WARN_UNUSED
351 rcl_ret_t
352 rcl_timer_is_ready(const rcl_timer_t * timer, bool * is_ready);
353 
355 
385 RCL_PUBLIC
386 RCL_WARN_UNUSED
387 rcl_ret_t
388 rcl_timer_get_time_until_next_call(const rcl_timer_t * timer, int64_t * time_until_next_call);
389 
391 
409 RCL_PUBLIC
410 RCL_WARN_UNUSED
411 rcl_ret_t
412 rcl_timer_get_next_call_time(const rcl_timer_t * timer, int64_t * next_call_time);
413 
415 
441 RCL_PUBLIC
442 RCL_WARN_UNUSED
443 rcl_ret_t
444 rcl_timer_get_time_since_last_call(const rcl_timer_t * timer, int64_t * time_since_last_call);
445 
447 
468 RCL_PUBLIC
469 RCL_WARN_UNUSED
470 rcl_ret_t
471 rcl_timer_get_period(const rcl_timer_t * timer, int64_t * period);
472 
474 
499 RCL_PUBLIC
500 RCL_WARN_UNUSED
501 rcl_ret_t
502 rcl_timer_exchange_period(const rcl_timer_t * timer, int64_t new_period, int64_t * old_period);
503 
505 
522 RCL_PUBLIC
523 RCL_WARN_UNUSED
524 rcl_timer_callback_t
525 rcl_timer_get_callback(const rcl_timer_t * timer);
526 
528 
549 RCL_PUBLIC
550 RCL_WARN_UNUSED
551 rcl_timer_callback_t
552 rcl_timer_exchange_callback(rcl_timer_t * timer, const rcl_timer_callback_t new_callback);
553 
555 
576 RCL_PUBLIC
577 RCL_WARN_UNUSED
578 rcl_ret_t
579 rcl_timer_cancel(rcl_timer_t * timer);
580 
582 
605 RCL_PUBLIC
606 RCL_WARN_UNUSED
607 rcl_ret_t
608 rcl_timer_is_canceled(const rcl_timer_t * timer, bool * is_canceled);
609 
611 
631 RCL_PUBLIC
632 RCL_WARN_UNUSED
633 rcl_ret_t
634 rcl_timer_reset(rcl_timer_t * timer);
635 
637 
655 RCL_PUBLIC
656 RCL_WARN_UNUSED
657 const rcl_allocator_t *
658 rcl_timer_get_allocator(const rcl_timer_t * timer);
659 
661 
674 RCL_PUBLIC
675 RCL_WARN_UNUSED
676 rcl_guard_condition_t *
677 rcl_timer_get_guard_condition(const rcl_timer_t * timer);
678 
680 
699 RCL_PUBLIC
700 RCL_WARN_UNUSED
701 rcl_ret_t
702 rcl_timer_set_on_reset_callback(
703  const rcl_timer_t * timer,
704  rcl_event_callback_t on_reset_callback,
705  const void * user_data);
706 
707 #ifdef __cplusplus
708 }
709 #endif
710 
711 #endif // RCL__TIMER_H_
rcl_allocator_t
rcutils_allocator_t rcl_allocator_t
Encapsulation of an allocator.
Definition: allocator.h:31
guard_condition.h
rcl_clock_s
Encapsulation of a time source.
Definition: time.h:138
rcl_context_s
Encapsulates the non-global state of an init/shutdown cycle.
Definition: context.h:114
rcl_guard_condition_s
Handle for a rcl guard condition.
Definition: guard_condition.h:36
rcl_timer_call_info_s
Structure which encapsulates timer information when called.
Definition: timer.h:56
rcl_timer_impl_s
Definition: timer.c:31
rcl_timer_on_reset_callback_data_s
Structure which encapsulates the on reset callback data.
Definition: timer.h:48
rcl_timer_s
Structure which encapsulates a ROS Timer.
Definition: timer.h:41
rcl_timer_s::impl
rcl_timer_impl_t * impl
Private implementation pointer.
Definition: timer.h:43
rcl_time_point_value_t
rcutils_time_point_value_t rcl_time_point_value_t
A single point in time, measured in nanoseconds since the Unix epoch.
Definition: time.h:46
rcl_timer_get_next_call_time
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_get_next_call_time(const rcl_timer_t *timer, int64_t *next_call_time)
Retrieve the time when the next call to rcl_timer_call() shall occur.
Definition: timer.c:347
rcl_timer_get_time_since_last_call
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_get_time_since_last_call(const rcl_timer_t *timer, int64_t *time_since_last_call)
Retrieve the time since the previous call to rcl_timer_call() occurred.
rcl_timer_callback_t
void(* rcl_timer_callback_t)(rcl_timer_t *, int64_t)
User callback signature for timers.
Definition: timer.h:74
rcl_timer_get_time_until_next_call
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_get_time_until_next_call(const rcl_timer_t *timer, int64_t *time_until_next_call)
Calculate and retrieve the time until the next call in nanoseconds.
Definition: timer.c:363
rcl_timer_call
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_call(rcl_timer_t *timer)
Call the timer's callback and set the last call time.
Definition: timer.c:267
rcl_timer_reset
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_reset(rcl_timer_t *timer)
Reset a timer.
Definition: timer.c:466
rcl_timer_get_period
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_get_period(const rcl_timer_t *timer, int64_t *period)
Retrieve the period of the timer.
Definition: timer.c:400
rcl_timer_set_on_reset_callback
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_set_on_reset_callback(const rcl_timer_t *timer, rcl_event_callback_t on_reset_callback, const void *user_data)
Set the on reset callback function for the timer.
Definition: timer.c:515
rcl_timer_exchange_period
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_exchange_period(const rcl_timer_t *timer, int64_t new_period, int64_t *old_period)
Exchange the period of the timer and return the previous period.
Definition: timer.c:410
rcl_timer_get_callback
RCL_PUBLIC RCL_WARN_UNUSED rcl_timer_callback_t rcl_timer_get_callback(const rcl_timer_t *timer)
Return the current timer callback.
Definition: timer.c:425
rcl_timer_exchange_callback
RCL_PUBLIC RCL_WARN_UNUSED rcl_timer_callback_t rcl_timer_exchange_callback(rcl_timer_t *timer, const rcl_timer_callback_t new_callback)
Exchange the current timer callback and return the current callback.
Definition: timer.c:433
rcl_timer_init2
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_init2(rcl_timer_t *timer, rcl_clock_t *clock, rcl_context_t *context, int64_t period, const rcl_timer_callback_t callback, rcl_allocator_t allocator, bool autostart)
Initialize a timer.
Definition: timer.c:144
rcl_timer_cancel
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_cancel(rcl_timer_t *timer)
Cancel a timer.
Definition: timer.c:443
rcl_timer_t
struct rcl_timer_s rcl_timer_t
Structure which encapsulates a ROS Timer.
rcl_timer_get_guard_condition
RCL_PUBLIC RCL_WARN_UNUSED rcl_guard_condition_t * rcl_timer_get_guard_condition(const rcl_timer_t *timer)
Retrieve a guard condition used by the timer to wake the waitset when using ROSTime.
Definition: timer.c:506
rcl_timer_call_info_t
struct rcl_timer_call_info_s rcl_timer_call_info_t
Structure which encapsulates timer information when called.
rcl_timer_clock
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_clock(const rcl_timer_t *timer, rcl_clock_t **clock)
Retrieve the clock of the timer.
Definition: timer.c:257
rcl_timer_call_with_info
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_call_with_info(rcl_timer_t *timer, rcl_timer_call_info_t *call_info)
Same as rcl_timer_call() except that it also retrieves the actual and expected call time.
Definition: timer.c:274
rcl_timer_on_reset_callback_data_t
struct rcl_timer_on_reset_callback_data_s rcl_timer_on_reset_callback_data_t
Structure which encapsulates the on reset callback data.
rcl_get_zero_initialized_timer
RCL_PUBLIC RCL_WARN_UNUSED rcl_timer_t rcl_get_zero_initialized_timer(void)
Return a zero initialized timer.
Definition: timer.c:59
rcl_timer_fini
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_fini(rcl_timer_t *timer)
Finalize a timer.
Definition: timer.c:228
rcl_timer_is_canceled
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_is_canceled(const rcl_timer_t *timer, bool *is_canceled)
Retrieve the canceled state of a timer.
Definition: timer.c:456
rcl_timer_init
RCL_PUBLIC rcl_ret_t rcl_timer_init(rcl_timer_t *timer, rcl_clock_t *clock, rcl_context_t *context, int64_t period, const rcl_timer_callback_t callback, rcl_allocator_t allocator)
Definition: timer.c:130
rcl_timer_is_ready
RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_timer_is_ready(const rcl_timer_t *timer, bool *is_ready)
Calculates whether or not the timer should be called.
Definition: timer.c:329
rcl_timer_get_allocator
RCL_PUBLIC RCL_WARN_UNUSED const rcl_allocator_t * rcl_timer_get_allocator(const rcl_timer_t *timer)
Return the allocator for the timer.
Definition: timer.c:498
rcl_ret_t
rmw_ret_t rcl_ret_t
The type that holds an rcl return code.
Definition: types.h:24
Generated by doxygen 1.9.1