SWI-Prolog -- API-function PL_cut

Availability:C-language interface function

int PL_cut_query(qid_t qid)

Discards the query, but does not delete any of the data created by the query. It just invalidates qid, allowing for a new call to PL_open_query() in this context. PL_cut_query() may invoke cleanup handlers (see setup_call_cleanup/3) and therefore may experience exceptions. If an exception occurs the return value is FALSE and the exception is accessible through PL_exception(0).

An example of a handler that can trigger an exception in PL_cut_query() is:

test_setup_call_cleanup(X) :-
    setup_call_cleanup(
        true,
        between(1, 5, X),
        throw(error)).

where PL_next_solution() returns TRUE on the first result and the throw(error) will only run when PL_cut_query() or PL_close_query() is run. On the other hand, if the goal in setup_call_cleanup/3 has completed (failure, exception, deterministic success), the cleanup handler will have done its work before control gets back to Prolog and therefore PL_next_solution() will have generated the exception. The return value PL_S_NOT_INNER is returned if qid is not the innermost query.