|
38 | 38 | * :class:`py_trees.decorators.EternalGuard` |
39 | 39 | * :class:`py_trees.decorators.Inverter` |
40 | 40 | * :class:`py_trees.decorators.OneShot` |
| 41 | +* :class:`py_trees.decorators.OnTerminate` |
41 | 42 | * :class:`py_trees.decorators.Repeat` |
42 | 43 | * :class:`py_trees.decorators.Retry` |
43 | 44 | * :class:`py_trees.decorators.StatusToBlackboard` |
@@ -920,3 +921,79 @@ def update(self) -> common.Status: |
920 | 921 | the behaviour's new status :class:`~py_trees.common.Status` |
921 | 922 | """ |
922 | 923 | return self.decorated.status |
| 924 | + |
| 925 | + |
| 926 | +class OnTerminate(Decorator): |
| 927 | + """ |
| 928 | + Trigger the child for a single tick on :meth:`terminate`. |
| 929 | +
|
| 930 | + Always return :data:`~py_trees.common.Status.RUNNING` and on |
| 931 | + on :meth:`terminate`, call the child's |
| 932 | + :meth:`~py_trees.behaviour.Behaviour.update` method, once. |
| 933 | +
|
| 934 | + This is useful to cleanup, restore a context switch or to |
| 935 | + implement a finally-like behaviour. |
| 936 | +
|
| 937 | + .. seealso:: :meth:`py_trees.idioms.eventually` |
| 938 | +
|
| 939 | + NB: If you need to persist the execution of the 'finally'-like block for more |
| 940 | + than a single tick, you'll need to build that explicitly into your tree. There |
| 941 | + are various ways of doing so (with and without the blackboard). One pattern |
| 942 | + that works: |
| 943 | +
|
| 944 | + .. code-block:: |
| 945 | +
|
| 946 | + [o] Selector |
| 947 | + {-} Sequence |
| 948 | + --> Work |
| 949 | + --> Finally (Triggers on Success) |
| 950 | + {-} Sequence |
| 951 | + --> Finally (Triggers on Failure) |
| 952 | + --> Failure |
| 953 | + """ |
| 954 | + |
| 955 | + def __init__(self, name: str, child: behaviour.Behaviour): |
| 956 | + """ |
| 957 | + Initialise with the standard decorator arguments. |
| 958 | +
|
| 959 | + Args: |
| 960 | + name: the decorator name |
| 961 | + child: the child to be decorated |
| 962 | + """ |
| 963 | + super(OnTerminate, self).__init__(name=name, child=child) |
| 964 | + |
| 965 | + def tick(self) -> typing.Iterator[behaviour.Behaviour]: |
| 966 | + """ |
| 967 | + Bypass the child when ticking. |
| 968 | +
|
| 969 | + Yields: |
| 970 | + a reference to itself |
| 971 | + """ |
| 972 | + self.logger.debug(f"{self.__class__.__name__}.tick()") |
| 973 | + self.status = self.update() |
| 974 | + yield self |
| 975 | + |
| 976 | + def update(self): |
| 977 | + """ |
| 978 | + Return with :data:`~py_trees.common.Status.RUNNING`. |
| 979 | +
|
| 980 | + Returns: |
| 981 | + the behaviour's new status :class:`~py_trees.common.Status` |
| 982 | + """ |
| 983 | + return common.Status.RUNNING |
| 984 | + |
| 985 | + def terminate(self, new_status: common.Status) -> None: |
| 986 | + """Tick the child behaviour once.""" |
| 987 | + self.logger.debug( |
| 988 | + "{}.terminate({})".format( |
| 989 | + self.__class__.__name__, |
| 990 | + "{}->{}".format(self.status, new_status) |
| 991 | + if self.status != new_status |
| 992 | + else f"{new_status}", |
| 993 | + ) |
| 994 | + ) |
| 995 | + if new_status == common.Status.INVALID: |
| 996 | + self.decorated.tick_once() |
| 997 | + # Do not need to stop the child here - this method |
| 998 | + # is only called by Decorator.stop() which will handle |
| 999 | + # that responsibility immediately after this method returns. |
0 commit comments