The various PL_*() functions in SWI-Prolog.h have
corresponding Plx_*() functions, defined in SWI-cpp2-plx.h,
which is always included by SWI-cpp2.h. There are three
kinds of wrappers, with the appropriate one being chosen according to
the semantics of the wrapped function:
- “as-is” - the PL_*() function cannot cause an error. If
it has a return value, the caller will want to use it.
- “exception wrapper” - the PL_*() function can return
false,
indicating an error. The Plx_*() function checks for this and throws a PlException
object containing the error. The wrapper uses template<typename
C_t> C_t PlEx(C_t rc),
where C_t is the return type of the PL_*() function.
- “success, failure, or error” - the PL_*() function can
return
true if it succeeds and false if it fails or
has a runtime error. If it fails, the wrapper checks for a Prolog error
and throws a PlException object containing the error. The
wrapper uses template<typename C_t> C_t PlWrap(C_t
rc), where C_t is the return type of the PL_*()
function.
A few PL_*() functions do not have a corresponding Plx*() function
because they do not fit into one of these categories. For example,
PL_next_solution() has multiple return values (PL_S_EXCEPTION,
PL_S_LAST, etc.) if the query was opened with the
PL_Q_EXT_STATUS flag.
Most of the PL_*() functions whose first argument is of type
term_t, atom_t, etc. have corresponding
methods in classes PlTerm, PlAtom, etc.
Important: You should use the Plx_*() wrappers only in the
context of a PREDICATE() call,
which will handle any C++ exceptions. Some blob callbacks can also
handle an exception (see
section 2.6.8). Everywhere else,
the result of calling a Plx_*() function is unpredicatable - probably a
crash.
