The current interface can be entirely defined in the .h
file using inlined code. This approach has a few advantages: as no C++
code is in the Prolog kernel, different C++ compilers with different
name-mangling schemas can cooperate smoothly. However, inlining
everything can lead to code bloat, so the larger functions and methods
have been put into a .cpp file that can be either compiled
separately (by the same compiler as used by the foreign predicate) or
inlined as if it were part of the .h file.
Also, changes to the header file have no consequences to binary compatibility with the SWI-Prolog kernel. This makes it possible to have different versions of the header file with few compatibility consequences.
As of 2023-04, some details remain to be decided, mostly to do with
encodings. A few methods have a PlEncoding optional
parameter (e.g., PlTerm::as_string()), but this hasn't yet been extended
to all methods that take or return a string. Also, the details of how
the default encoding is set have not yet been decided.
As of 2023-04, the various error convenience classes do not fully
match what the equivalent C functions do. That is, throw
PlInstantiationError(A1) does not result in the same context and
traceback information that would happen from
Plx_instantiation_error(A1.unwrap()); throw PlFail(). See
section 2.20.2.
The Plx_*() wrappers may require small adjustments in whether their
return values require [[nodiscard]] or whether their return
values should be treated as an error.
The implementation of PlException is likely to change
somewhat in the future. Currently, to ensure that the exception term has
a sufficient lifetime, it is serialized using PL_record_external().
In future, if this proves unnecessary, the term will be stored as-is.
The API will not change if this implementation detail changes.