Updates for the cancel checker (PR #4148) (#531)

* Add Jazzy migration guide for cancel checker

Signed-off-by: Kemal Bektas <kemal.bektas@node-robotics.com>

* Update planner configurations for terminal_checking_interval

Signed-off-by: Kemal Bektas <kemal.bektas@node-robotics.com>

* Update Iron.rst

---------

Signed-off-by: Kemal Bektas <kemal.bektas@node-robotics.com>
Co-authored-by: Kemal Bektas <kemal.bektas@node-robotics.com>
Co-authored-by: Steve Macenski <stevenmacenski@gmail.com>

Author: 3 people

configuration/packages/configuring-thetastar.rst

@@ -81,6 +81,17 @@ The parameters of the planner are:
   Description
     Whether to allow planning in unknown space.
 
+:``<name>``.terminal_checking_interval:
+
+  ==== =======
+  Type Default                                                   
+  ---- -------
+  int  5000            
+  ==== =======
+
+  Description
+    Number of iterations between checking if the goal has been cancelled or planner timed out
+
 .. Note::
   Do go through the README file available on this repo's link to develop a better understanding of how you could tune this planner.
   This planner requires you to tune the `cost_scaling_factor` parameter of your costmap too, to get good results.   

configuration/packages/smac/configuring-smac-2d.rst

@@ -81,6 +81,17 @@ Parameters
   Description
     Maximum number of iterations after the search is within ``tolerance`` before returning approximate path with best heuristic if exact path is not found.
 
+:``<name>``.terminal_checking_interval:
+
+  ==== =======
+  Type Default                                                   
+  ---- -------
+  int  5000            
+  ==== =======
+
+  Description
+    Number of iterations between checking if the goal has been cancelled or planner timed out
+
 :``<name>``.max_planning_time:
 
   ====== =======

configuration/packages/smac/configuring-smac-hybrid.rst

@@ -81,6 +81,17 @@ Parameters
   Description
     Maximum number of iterations once a visited node is within the goal tolerances to continue to try to find an exact match before returning the best path solution within tolerances. Negative values convert to infinite.
 
+:``<name>``.terminal_checking_interval:
+
+  ==== =======
+  Type Default                                                   
+  ---- -------
+  int  5000            
+  ==== =======
+
+  Description
+    Number of iterations between checking if the goal has been cancelled or planner timed out
+
 :``<name>``.max_planning_time:
 
   ====== =======

configuration/packages/smac/configuring-smac-lattice.rst

@@ -63,6 +63,17 @@ Parameters
   Description
     Maximum number of iterations once a visited node is within the goal tolerances to continue to try to find an exact match before returning the best path solution within tolerances.
 
+:``<name>``.terminal_checking_interval:
+
+  ==== =======
+  Type Default                                                   
+  ---- -------
+  int  5000            
+  ==== =======
+
+  Description
+    Number of iterations between checking if the goal has been cancelled or planner timed out
+
 :``<name>``.max_planning_time:
 
   ====== =======

migration/Iron.rst

@@ -254,3 +254,19 @@ In the GIF, it can be seen that there are two controller_ids namely, `FollowPath
 In this case, the `FollowPath` is the default controller_id. The difference between the two controller_ids is that HighSpeedFollowPath has a higher max velocity compared to the FollowPath. This difference can be well noted in the GIF.
 
 .. attention:: If a server is unavailable, then the combo box or the drop down list of the particular component will be empty.
+
+Cancel Checker Interface For GlobalPlanner
+*******************************************
+`PR #4148 <https://github.com/ros-planning/navigation2/pull/4148>`_ introduces a new interface for the ``GlobalPlanner`` to allow for the cancellation of the current planning task.
+Before the planners would continue to plan even if the goal was cancelled, now they can check it and stop planning if the goal is cancelled.
+New interface for ``GlobalPlanner::createPlan``:
+
+.. code-block:: cpp
+
+    virtual nav_msgs::msg::Path createPlan(
+      const geometry_msgs::msg::PoseStamped & start,  
+      const geometry_msgs::msg::PoseStamped & goal,  
+      std::function<bool()> cancel_checker)
+
+This is implemented for all the planners in the stack, you can check them for the example use of ``cancel_checker`` function (simply check ``cancel_checker()``).
+Smac and Theta* planners have a new parameter ``terminal_checking_interval`` which is the frequency of the cancel or timeout checking in terms of number of iterations.