Skip to content

Commit

Permalink
Clarify and add some examples to Callback groups docs (ros2#3584)
Browse files Browse the repository at this point in the history
* clarify and add examples

Co-authored-by: Chris Lalancette <clalancette@gmail.com>
  • Loading branch information
tonynajjar and clalancette committed May 15, 2023
1 parent 9e03334 commit 2331e99
Showing 1 changed file with 25 additions and 22 deletions.
47 changes: 25 additions & 22 deletions source/How-To-Guides/Using-callback-groups.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ In short:
executed in parallel - essentially making it as if the callbacks in the group
were executed by a SingleThreadedExecutor.
* Reentrant Callback Group allows the executor to schedule and execute
the group's callbacks in any way the it sees fit, without restrictions.
the group's callbacks in any way it sees fit, without restrictions.
This means that, in addition to different callbacks being run parallel
to each other, different instances of the same callback may also be
executed concurrently.
Expand Down Expand Up @@ -108,27 +108,30 @@ Controlling execution
In order to control execution with callback groups, one can consider the
following guidelines.

* Register callbacks that should never be executed in parallel to the same
Mutually Exclusive Callback Group.
An example case might be that the callbacks are accessing shared
critical and non-thread-safe resources.
* If you have a callback whose execution instances need to be able to overlap
with each other, register it to a Reentrant Callback Group.
An example case could be an action server that needs to be able to process
several action calls in parallel to each other.
* If you have different callbacks that require to be potentially executed
in parallel to one another, register them to

* a Reentrant Callback Group, or
* different Mutually Exclusive Callback Groups (this option is good if you
want the callbacks to not overlap themselves or also need thread
safety with respect to some other callbacks)
or different callback groups of any type (choose the types according
to other criteria).

Note that the option in the list is a valid way of allowing parallel
execution for different callbacks, and can even be more desirable than simply
registering everything into one Reentrant Callback Group.
For the interaction of an individual callback with itself:

* Register it to a Reentrant Callback Group if it should be executed in parallel to itself.
An example case could be an action/service server that needs to be able to
process several action calls in parallel to each other.

* Register it to a Mutually Exclusive Callback Group if it should **never** be executed in parallel to itself.
An example case could be a timer callback that runs a control loop that publishes control commands.

For the interaction of different callbacks with each other:

* Register them to the same Mutually Exclusive Callback Group if they should **never** be executed in parallel.
An example case could be that the callbacks are accessing shared critical and non-thread-safe resources.

If they should be executed in parallel, you have two options,
depending on whether the individual callbacks should be able to overlap themselves or not:

* Register them to different Mutually Exclusive Callback Groups (no overlap of the individual callbacks)

* Register them to a Reentrant Callback Group (overlap of the individual callbacks)

An example case of running different callbacks in parallel is a Node that has
a synchronous service client and a timer calling this service.
See the detailed example below.

Avoiding deadlocks
------------------
Expand Down

0 comments on commit 2331e99

Please sign in to comment.