SWI-Prolog -- API-function PL_cut

Documentation
- Reference manual
  - Foreign Language Interface
    - The Foreign Include File
      - Calling Prolog from C
        
        Initiating a query from C
        
        PL_open_query()
        
        PL_next_solution()
        
        PL_cut_query()
        
        PL_close_query()
        
        PL_current_query()
        
        PL_query_engine()
        
        PL_call_predicate()
        
        PL_call()
- Packages

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, determinitic 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.