undo/1

Availability:built-in

undo(:Goal)

Add Goal to the trail. Goal is executed as ignore/1 on the first opportunity after backtracking to a point before the call to Goal. This predicate is intended to make otherwise persistent changes to the database or created by foreign procedures backtrackable if it is possible to define a goal that reverts the effect of the initial call. A typical use case is to define a backtrackable assert.

b_assertz(Term) :-
    assertz(Term, Ref),
    undo(erase(Ref)).

Without undo/1 we can achieve something similar by leaving a choicepoint using the almost portable^{80assertz/2
is not part of the ISO standard but supported by multiple systems.} alternative below.

b_assertz(Term) :-
    assertz(Term, Ref),
    (   true
    ;   erase(Ref),
        fail
    ).

The undo/1 based solution avoids leaving a choice point open and, more importantly, keeps undoing the assert also if the choice point from the second alternative is pruned.

Currently the following remarks apply

Goal is copied when it is registered.
“First opportunity” means after backtracking or at the first call port reached.
Multiple undo goals may be scheduled that are executed as a batch. If multiple goals raise an exception, the most urgent is preserved after all goals have been executed.
It is not allowed for Goal to call undo/1. An attempt to do so results in a permission_error exception.
Note that an exception that is caught higher in the call stack backtracks and therefore ensures Goal is called.