Did you know ... Search Documentation:
Predicate setup_call_cleanup/3
Availability:built-in
Sourcesetup_call_cleanup(:Setup, :Goal, :Cleanup)
Calls (once(Setup), Goal). If Setup succeeds, Cleanup will be called exactly once after Goal is finished: either on failure, deterministic success, commit, or an exception. The execution of Setup is protected from asynchronous interrupts like call_with_time_limit/2 (package clib) or thread_signal/2. In most uses, Setup will perform temporary side-effects required by Goal that are finally undone by Cleanup.

Success or failure of Cleanup is ignored, and choice points it created are destroyed (as once/1). If Cleanup throws an exception, this is executed as normal while it was not triggered as the result of an exception the exception is propagated as normal. If Cleanup was triggered by an exception the rules are described in section 4.10.1

Typically, this predicate is used to cleanup permanent data storage required to execute Goal, close file descriptors, etc. The example below provides a non-deterministic search for a term in a file, closing the stream as needed. 

term_in_file(Term, File) :-
        setup_call_cleanup(open(File, read, In),
                           term_in_stream(Term, In),
                           close(In) ).

term_in_stream(Term, In) :-
        repeat,
        read(In, T),
        (   T == end_of_file
        ->  !, fail
        ;   T = Term
        ).

Note that it is impossible to implement this predicate in Prolog. The closest approximation would be to read all terms into a list, close the file and call member/2. Without setup_call_cleanup/3 there is no way to gain control if the choice point left by repeat/0 is removed by a cut or an exception.

setup_call_cleanup/3 can also be used to test determinism of a goal, providing a portable alternative to deterministic/1: 

?- setup_call_cleanup(true,(X=1;X=2), Det=yes).

X = 1 ;

X = 2,
Det = yes ;

This predicate is under consideration for inclusion into the ISO standard. For compatibility with other Prolog implementations see call_cleanup/2.

Tag confusing pages with doc-needs-help|Tags are associated to your profile if you are logged in|Report abuse
Tags:
  • cleanup
  • doc-needs-help
  • try_finally
LogicalCaptain said (2020-03-20T12:57:50):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain.

Note

When an exception is thrown from Goal in interactive mode, the tracer is triggered (unless you have set set_prolog_flag(debug_on_error,false)) and that just before the CLeanup goal and you will notice that setup_call_cleanup/3 is actually setup_call_catcher_cleanup/4.

Another example:

The example given in the text is hard to understand. Here is another one:

alty :- format("1st clause of alty/0 called\n").
alty :- format("2nd clause of alty/0 called\n").
alty :- format("3rd clause of alty/0 called\n").

outro(yes) :- format("In outro/1: called!\n").

check_outro(D) :-
   (D==yes
    -> format("outro/1 has been called")
    ;  format("outro/1 has not yet been called")).

testy_nocut :-
   setup_call_cleanup(true,alty,outro(D)),
   format("After setup_call_cleanup/3\n"),
   check_outro(D).

testy_withcut :-
   setup_call_cleanup(true,alty,outro(D)),
   format("After setup_call_cleanup/3, prior to cut\n"),
   !,
   check_outro(D).

Running testy_nocut/0. outro is invoked once alty returns without open choicepoints.

?- testy_nocut.
1st clause of alty/0 called
After setup_call_cleanup/3
outro/1 has not yet been called
true ;
2nd clause of alty/0 called
After setup_call_cleanup/3
outro/1 has not yet been called
true ;
3rd clause of alty/0 called
In outro/1: called!
After setup_call_cleanup/3
outro/1 has been called
true.

Running testy_withcut/0. outro is (somewhat magically) invoked once the cut has been traversed. Just by scanning the code one would not expect this to happen.

This is akin to installing a handler on the OR-node of the search tree, which is run once there are no more choices left or choices have been cut off.

?- testy_withcut.
1st clause of alty/0 called
After setup_call_cleanup/3, prior to cut
In outro/1: called!
outro/1 has been called
true.

Example of determinism in the cleanup procedure

?- setup_call_cleanup(true,member(X,[1,2]),member(Y,[a,b])).
X = 1 ;
X = 2,    % member(X,[1,2]) has no more solutions, so the cleanup goal is called
Y = a.    % member(Y,[a,b]) is called as with once/1

Example of a goal generating an exception

alty_with_exception :- format("1st clause of alty/0 called\n").
alty_with_exception :- type_error("the cake is a lie","cake").

outro(yes) :- format("In outro/1: called!\n").

check_outro(D) :-
   (D==yes
    -> format("outro/1 has been called")
    ;  format("outro/1 has not yet been called")).

testy_with_exception :-
   setup_call_cleanup(true,alty_with_exception,outro(D)),
   format("After setup_call_cleanup/3\n"),
   check_outro(D).

Then outro/1 is called when the exception is thrown:

?- catch(testy_with_exception,ExTerm,format("Exception: ~q\n",[ExTerm])).
1st clause of alty/0 called
After setup_call_cleanup/3
outro/1 has not yet been called
true ;
In outro/1: called!
Exception: error(type_error("the cake is a lie","cake"),_6068)
ExTerm = error(type_error("the cake is a lie", "cake"), _6068).

Compare with Java's "finally"

The cleanup goal is basically the finally block of (say) Java (or other bracy languages):

The finally Block:

"The finally block always executes when the try block exits. This ensures that the finally block is executed even if an unexpected exception occurs."