SWI-Prolog atoms as well as strings can represent arbitrary binary data of arbitrary length. This facility is attractive for storing foreign data such as images in an atom. An atom is a unique handle to this data and the atom garbage collector is able to destroy atoms that are no longer referenced by the Prolog engine. This property of atoms makes them attractive as a handle to foreign resources, such as Java atoms, Microsoft's COM objects, etc., providing safe combined garbage collection.
To exploit these features safely and in an organised manner, the SWI-Prolog foreign interface allows for creating `atoms' with additional type information. The type is represented by a structure holding C function pointers that tell Prolog how to handle releasing the atom, writing it, sorting it, etc. Two atoms created with different types can represent the same sequence of bytes. Atoms are first ordered on the rank number of the type and then on the result of the compare() function. Rank numbers are assigned when the type is registered.
The type PL_blob_t represents a structure with the
layout displayed below. The structure contains additional fields at the
... for internal bookkeeping as well as future extensions.
typedef struct PL_blob_t
{ uintptr_t magic; /* PL_BLOB_MAGIC */
uintptr_t flags; /* Bitwise or of PL_BLOB_* */
char * name; /* name of the type */
int (*release)(atom_t a);
int (*compare)(atom_t a, atom_t b);
int (*write)(IOSTREAM *s, atom_t a, int flags);
void (*acquire)(atom_t a);
...
} PL_blob_t;
For each type, exactly one such structure should be allocated. Its
first field must be initialised to PL_BLOB_MAGIC. The
flags is a bitwise or of the following constants:
PL_BLOB_UNIQUE
is also specified, uniqueness is determined by comparing the pointer
rather than the data pointed at.
The name field represents the type name as available to
Prolog. See also current_blob/2.
The other fields are function pointers that must be initialised to
proper functions or NULL to get the default behaviour of
built-in atoms. Below are the defined member functions:
FALSE the atom garbage collector will not
reclaim the atom.PL_WRT_* flags defined
in
SWI-Prolog.h. This prototype is available if the
undocumented SWI-Stream.h is included before
SWI-Prolog.h.
If this function is not provided, write/1
emits the content of the blob for blobs of type PL_BLOB_TEXT
or a string of the format <#hex data>
for binary blobs.
If a blob type is registered from a loadable object (shared object or DLL) the blob type must be deregistered before the object may be released.
unregistered, avoiding further
reference to the type structure, functions referred by it, as well as
the data. This function returns TRUE if no blobs of this
type existed and FALSE otherwise. PL_unregister_blob_type()
is intended for the uninstall() hook of foreign modules, avoiding
further references to the module.
The blob access functions are similar to the atom accessing functions. Blobs being atoms, the atom functions operate on blobs and vice versa. For clarity and possible future compatibility issues, however, it is not advised to rely on this.
FALSE) or the blob is a
reference to an existing blob (TRUE). Reporting
new/existing can be used to deal with external objects having their own
reference counts. If the return is TRUE this reference
count must be incremented, and it must be decremented on blob
destruction callback. See also
PL_put_atom_nchars().TRUE. Otherwise return FALSE. Each result
pointer may be NULL, in which case the requested
information is ignored.