From c3c0789c7a824dc59d5a703be956bb2ab8bb9c58 Mon Sep 17 00:00:00 2001 From: William Woodall Date: Wed, 12 Dec 2018 15:28:25 -0800 Subject: [PATCH] update docs about possibility of rcl_take no taking (#356) * update rcl_wait doc with respect to subs and possibility of failing takes * add a note about possible failing takes in rcl_take docs --- rcl/include/rcl/subscription.h | 5 +++++ rcl/include/rcl/wait.h | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/rcl/include/rcl/subscription.h b/rcl/include/rcl/subscription.h index 3061175..6bd3e5d 100644 --- a/rcl/include/rcl/subscription.h +++ b/rcl/include/rcl/subscription.h @@ -217,6 +217,11 @@ rcl_subscription_get_default_options(void); * if one is available. * If taken is false after calling, then the ROS message will be unmodified. * + * The taken boolean may be false even if a wait set reports that the + * subscription was ready to be taken from in some cases, e.g. when the + * state of the subscription changes it may cause the wait set to wake up + * but subsequent takes to fail to take anything. + * * If allocation is required when taking the message, e.g. if space needs to * be allocated for a dynamically sized array in the target message, then the * allocator given in the subscription options is used. diff --git a/rcl/include/rcl/wait.h b/rcl/include/rcl/wait.h index 4e7673d..70d89a6 100644 --- a/rcl/include/rcl/wait.h +++ b/rcl/include/rcl/wait.h @@ -349,7 +349,9 @@ rcl_wait_set_add_service( * this function returns. * Items that are not `NULL` are ready, where ready means different things based * on the type of the item. - * For subscriptions this means there are messages that can be taken. + * For subscriptions this means there may be messages that can be taken, or + * perhaps that the state of the subscriptions has changed, in which case + * rcl_take may succeed but return with taken == false. * For guard conditions this means the guard condition was triggered. * * Expected usage: