1.11.13 Classes for the recorded database: PlRecord and PlRecordExternalCopy

The recorded database is has two wrappers, for supporting the internal records and external records.

Currently, the interface to internal records requires that the programmer explicitly call the dupicate() and erase() methods - in future, it is intended that this will be done automatically by a new PlRecord class, so that the internal records behave like “smart pointers” ; in the meantime, the PlRecord provides a trivial wrapper around the various recorded database functions.

The class PlRecord supports the following methods:

PlRecord(PlTerm)

Constructor.

PlRecord(PlRecord)

Copy and move constructors. Currently these do not do any reference counting. The assignment operator is currently not supported.

 PlRecord()

Destructor. Currently this does not call PL_erase().

PlTerm term()

creates a term from the record, using PL_recorded().

void erase()

decrements the reference count of the record and deletes it if the count goes to zero, using PL_erase(). It is safe to do this multiple times on the same PlRecord object.

PlRecord duplicate()

increments the reference count of the record, using PL_duplicate_record().

The class PlRecord provides direct access to the reference counting aspects of the recorded term (through the duplicate() and erase() methods), but does not connect these with C++'s copy constructor, assignment operator, or destructor. If the recorded term is encapsulated within an object, then the containing object can use the duplicate() and erase() methods in its copy and move constructors and assignment operators (and the erase() method in the destructor).^{29The copy constructor and assignment use the duplicate() method; the move constructor and assignment use the duplicate() method to assign to the destination and the erase() method on the source; and the destructor uses erase().}

Alternatively, the std::shared_ptr or std::unique_ptr can be used with the supplied PlrecordDeleter, which calls the erase() method when the shared_ptr reference count goes to zero or when the std::unique_ptr goes out of scope.

For example:

std::shared_ptr<PlRecord> r(new PlRecord(t.record()), PlRecordDeleter());
assert(t.unify_term(r->term()));

The class PlRecordExternalCopy keeps the external record as an uninterpreted string (which may contain nulls). It supports the following methods.

PlRecordExternalCopy :: PlRecordExternalCopy(PlTerm t)

Creates a string using Pl_record_external(), copies it into the object then deletes the reference using PL_erase_external().

PlRecordExternalCopy :: PlRecordExternalCopy(const std::string& external)

Saves the external string (which is assumed to have been created using PL_record_external()).

PlRecordExternalCopy :: PlRecordExternalCopy(const char* external, size_t len)

Saves the external string (which is assumed to have been created using PL_record_external()).

PlTerm term()

creates a term from the saved external record string, using PL_recorded_external()).

static PlTerm term(const std::string& external)

Creates a term from the external record string. Equivalent to PlRecordExternalCopy(external).term().

static PlTerm term(const char* external)

Creates a term from the external record string. Equivalent to PlRecordExternalCopy(external,len).term() except the length is inferred from external’s contents.

const std::string& data()

Gets the external string that was created by the constructor.