Many of the functions of the foreign language interface involve
strings. Some of these strings point into static memory like those
associated with atoms. These strings are valid as long as the atom is
protected against atom garbage collection, which generally implies the
atom must be locked using PL_register_atom()
or be part of an accessible term. Other strings are more volatile.
Several functions provide a BUF_* flag that can be set to either BUF_STACK
(default) or
BUF_MALLOC. Strings returned by a function accepting
BUF_MALLOC must be freed using PL_free().
Strings returned using BUF_STACK are pushed on a stack that
is cleared when a foreign predicate returns control back to Prolog. More
fine grained control may be needed if functions that return strings are
called outside the context of a foreign predicate or a foreign predicate
creates many strings during its execution. Temporary strings are scoped
using these macros:
- void PL_STRINGS_MARK()
- void PL_STRINGS_RELEASE()
- These macros must be paired and create a C block ({...}). Any
string created using
BUF_STACK after PL_STRINGS_MARK()
is released by the corresponding PL_STRINGS_RELEASE().
These macros should be used like below. Note that strings returned by
any of the Prolog functions between this pair may be invalidated.
...
PL_STRINGS_MARK();
<operations involving strings>
PL_STRINGS_RELEASE();
...
The Prolog flag string_stack_tripwire
may be used to set a
tripwire to help finding places where scoping strings may help
reducing resources.
