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
ros2 · Dec 12, 2018 · c3c0789 · c3c0789
1 parent 1360c82
commit c3c0789
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 1 deletion.
diff --git 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
@@ -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: