In some applications it is useful to store and retrieve Prolog terms
from C code. For example, the XPCE graphical environment does this for
storing arbitrary Prolog data as slot-data of XPCE objects.
Please note that the returned handles have no meaning at the Prolog
level and the recorded terms are not visible from Prolog. The functions
PL_recorded()
and PL_erase()
are the only functions that can operate on the stored term.
Two groups of functions are provided. The first group (PL_record()
and friends) store Prolog terms on the Prolog heap for retrieval during
the same session. These functions are also used by recorda/3
and friends. The recorded database may be used to communicate Prolog
terms between threads.
- record_t PL_record(term_t
+t)
- Record the term t into the Prolog database as recorda/3
and return an opaque handle to the term. The returned handle remains
valid until PL_erase()
is called on it. PL_recorded()
is used to copy recorded terms back to the Prolog stack. Currently
aborts the process with a fatal error on failure. Future
versions may raise a resource exception and return
(record_t)0.
- record_t PL_duplicate_record(record_t
record)
- Return a duplicate of record. As records are read-only
objects this function merely increments the records reference count.
Returns
(record_t)0 if the record is an
external record (see PL_record_external()).
- bool PL_recorded(record_t
record, term_t -t)
- Copy a recorded term back to the Prolog stack. The same record may be
used to copy multiple instances at any time to the Prolog stack. Returns
TRUE
on success, and FALSE if there is not enough space on the
stack to accommodate the term. See also PL_record()
and PL_erase().
- void PL_erase(record_t
record)
- Remove the recorded term from the Prolog database, reclaiming all
associated memory resources.
The second group (headed by PL_record_external())
provides the same functionality, but the returned data has properties
that enable storing the data on an external device. It has been designed
for fast and compact storage of Prolog terms in an external database.
Here are the main features:
- Independent of session
Records can be communicated to another Prolog session and made visible
using PL_recorded_external().
- Binary
The representation is binary for maximum performance. The returned data
may contain zero bytes.
- Byte-order independent
The representation can be transferred between machines with different
byte order.
- No alignment restrictions
There are no memory alignment restrictions and copies of the record can
thus be moved freely. For example, it is possible to use this
representation to exchange terms using shared memory between different
Prolog processes.
- Compact
It is assumed that a smaller memory footprint will eventually outperform
slightly faster representations.
- Stable
The format is designed for future enhancements without breaking
compatibility with older records.
- char * PL_record_external(term_t
+t, size_t *len)
- Similar to PL_record(),
but the term is serialized such that it can be reloaded in another
Prolog session. This implies that atoms and functors are stored by their
content rather than their handle. As a result, PL_record_external()
fails (returning
NULL if the term contains blobs that cannot be
serialized, such as streams.
These functions are used to implement library library(fastrw)
as well as for storing Prolog terms in external databases such as
BerkeleyDB (library library(bdb)) or RocksDB. The
representation is optimized for plain atoms and numbers.
Records that are used only in the same Prolog process should use
PL_record()
as this can represent any term, is more compact and faster.
The returned string may be copied. Note that the string may contain
null bytes and is not null terminated. The length in bytes is returned
in len. After copying, the returned string may be discarded
using PL_erase_external().
PL_recorded_external()
is used to copy the term represented in the data back to the Prolog
stack. PL_recorded_external()
can be used on the returned string as well as on a copy.
- bool PL_recorded_external(const
char *record, term_t -t)
- Copy a recorded term back to the Prolog stack. The same record may be
used to copy multiple instances at any time to the Prolog stack. See
also PL_record_external()
and PL_erase_external().
- bool PL_erase_external(char
*record)
- Remove the recorded term from the Prolog database, reclaiming all
associated memory resources.