2.5.4 Wrapper functions

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:

• "as-is" - the PL_*() function cannot cause an error. If it has a return value, the caller will want to use it. (These are defined using the PLX_ASIS() and PLX_VOID() macros.)

• "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. (These are defined using the PLX_WRAP() macro.)

• "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. (These are defined using the PLX_EXCE() macro.)

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. Everywher else, results are unpredicatable (probably a crash).