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.11.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
LogicalCaptain said (2020-03-20T12:57:50):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain.

The example given in the text is incomprehensible, here is another one:

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

outro(yes) :- format("outro\n").

testy :- setup_call_cleanup(true,alty,outro(D)),format("HI!\n"),
         (D==yes ->
            format("alty is deterministic");
            format("alty has open choicepoints")).

testy2 :- setup_call_cleanup(true,alty,outro(D)),format("HI!\n"),!,
          (D==yes ->
            format("alty is deterministic");
            format("alty has open choicepoints")).

Running testy. outro is invoked once alty returns without any open choicepoints.

?- testy.
1st clause
HI!
alty has open choicepoints
true ;
2nd clause
HI!
alty has open choicepoints
true ;
3rd clause
outro
HI!
alty is deterministic
true.

Running testy2. outro is magically invoked once the cut has been traversed (after "HI").

Just by scanning the code one would not expect this to happen.

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

?- testy2.
1st clause
HI!
outro
alty is deterministic
true.
LogicalCaptain said (2020-03-20T12:36:53):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain.

Demo of determinism in the cleanup procedure:

?- setup_call_cleanup(true,member(X,[1,2]),member(Y,[a,b])).
X = 1 ;
X = 2,
Y = a.
LogicalCaptain said (2020-03-20T12:19:00):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain. 
intro :- format("intro\n").

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

outro :- format("outro\n").

Then

?- setup_call_cleanup(intro,alty,outro).
intro
1st clause
true ;
2nd clause
true ;
3rd clause
outro
true.
LogicalCaptain said (2020-03-20T11:01:57):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain.

This is a bit like try-with-resources in Java:

https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html

although there, a close() call is made for every resource declared implicitly. One does not need to specify it explicity:

static String readFirstLineFromFile(String path) throws IOException {
    try (BufferedReader br =
                   new BufferedReader(new FileReader(path))) {
        return br.readLine();
    }
}

A br.close() will be issued on success or exception.