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.

Examples

Read all lines to a list

Read all lines to a list

file_lines(File, Lines) :-
    setup_call_cleanup(open(File, read, In),
       stream_lines(In, Lines),
       close(In)).

stream_lines(In, Lines) :-
    read_string(In, _, Str),
    split_string(Str, "\n", "", Lines).

This loads all lines to memory as strings. If we use the Unix dictionary words:

?- file_lines("/usr/share/dict/words", Lines).
Words = ["A", "a", "aa", "aal", "aalii", "aam", "Aani", "aardvark", "aardwolf"|...].
Backtrack over lines in a file

Backtrack over lines in a file

file_line(File, Line) :-
    setup_call_cleanup(open(File, read, In),
        stream_line(In, Line),
        close(In)).

stream_line(In, Line) :-
    repeat,
    (   read_line_to_string(In, Line0),
        Line0 \== end_of_file
    ->  Line0 = Line
    ;   !,
        fail
    ).

This will backtrack over consecutive lines in the input. If we use the Unix dictionary words:

?- file_line("/usr/share/dict/words", Word).
Word = "A" ;
Word = "a" ;
Word = "aa" ;
Word = "aal" ; % and so on

This doesn't load all lines to memory, so it can be used with very large files.

See also
- read_line_to_codes/2 to read to a code list instead of a string
- read_string/5 for more control over the separator and stripping
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.

If you come from other programming languages

If you come from other programming languages, seeing

setup_call_cleanup(:Setup, :Goal, :Cleanup)

will make you think that "setup" and the "cleanup" are around the "goal", so that when the "goal" returns, "cleanup" is called. But this is not actually how to think about it. "cleanup" does not get called until "goal" has run out of substitutions, i.e. goals "to the right" of setup_call_cleanup will run with "cleanup" not called.

In fact, it is as if the "cleanup" goal had been injected on the left of Goal after a successful setup:

Written as

setup_call_cleanup(Setup, Goal, Cleanup), AnotherGoal.

This runs as:

Setup, Goal, AnotherGoal.

and after a successful Setup it actually becomes:

Cleanup, Goal, AnotherGoal.

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."

Example from library prolog_pack

Great example from library prolog_pack (file ./lib/swipl/library/prolog_pack.pl).

We read the headers of an archive file (zip, tar etc.) using a failure-driven loop. Note that the cleanup operation comes lexically before the code that deals with the "next result" (From file_base_name(InfoFile, 'pack.pl') till clause end).

archive_close(Handle) is only called at the end, when the loop is "done". This is a bit disconcerting.

pack_archive_info(Archive, Pack, [archive_size(Bytes)|Info], Strip) :-
    ensure_loaded_archive,
    size_file(Archive, Bytes),
    setup_call_cleanup(
        archive_open(Archive, Handle, []),
        (   repeat,
            (   archive_next_header(Handle, InfoFile)
            ->  true
            ;   !, fail
            )
        ),
        archive_close(Handle)),
    file_base_name(InfoFile, 'pack.pl'),
    atom_concat(Prefix, 'pack.pl', InfoFile),
    strip_option(Prefix, Pack, Strip),
    setup_call_cleanup(
        archive_open_entry(Handle, Stream),
        read_stream_to_terms(Stream, Info),
        close(Stream)),
    !,
    must_be(ground, Info),
    maplist(valid_info_term, Info).