1.10.1 PlCheckFail(), PlEx(), PlWrap<int>() convenience functions

If one of the C PL_*() functions in SWI-Prolog.h returns failure, this can be either a Prolog-style failure (e.g. from PL_unify() or PL_next_solution()) or an error. If the failure is due to an error, it's usually best to immediately return to Prolog - and this can be done with the PlEx() function, which turns a Prolog error into a C++ PlException. PlCheckFail() calls PlEx() and additionally throws PlFail() if the failure is for Prolog failure.

PlEx() calls PL_exception() to see if there is a Prolog exception; if so, the Prolog exception is converted to a PlException object, which is then thrown. For more details on the C++ exceptions, see section 1.15.

PlWrap<int>() is similar to PlEx() except that it returns the result of the call. This is useful for PlQuery::next_solution(), which doesn't do a check for whether the ‘false` return value is due to a failed query or an exception (PlQuery::next_solution() can return values other than true or false if the PlQuery object was created with the PL_Q_EXT_STATUS flag.

void PlCheckFail(bool rc)

If rc is false, throw PlFail to return control to Prolog with failure.

C_t PlWrap(C_t rc, qid_t qid = 0)

If rc indicates failure or an error, check for an error and throw a PlException if there was one; otherwise, return the rc.

void PlEx(C_t rc, qid_t qid = 0)

If rc is “false” (non-zero), throw PlFail to return control to Prolog with failure. This is the same as PlCheckFail() except it can also specify a qid_t query ID.