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 portable79assertz/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.
See also snapshot/1
and transaction/1.