While the blob is alive, neither its handle nor the location of the
contents (see PL_blob_data())
change. If the blob's type has the
PL_BLOB_UNIQUE
feature, the content of the blob must remain
unmodified. Blobs are only reclaimed by the atom garbage
collector. In this case the atom garbage collector calls the
release(f)unction
associated with the blob type and reclaims the memory allocated for the
content unless this is owned by the creator of the blob indicated by the PL_BLOB_NOCOPY
flag. After an
atom_t
value is reclaimed by the atom garbage collector,
the value may be reused for allocating a new blob or atom.
If foreign code stores the atom_t
handle in some
permanent location it must make sure the handle is registered
to prevent it from being garbage collected. If the handle is obtained
from a
term_t
object it is not registered because it is
protected by the term_t
object. This applies to e.g.,
PL_get_atom().
Functions that create a handle from data such as
PL_new_atom()
return a registered handle to prevent the asynchronous atom garbage
collector from reclaiming it immediately. Note that many of the API
functions create an atom or blob handle and use this to fill a
term_t
object, e.g., PL_unify_blob(), PL_unify_chars(),
etc. In this scenario the handle is protected by the term_t
object. Registering and unregistering atom_t
handles is
done by
PL_register_atom()
and PL_unregister_atom().
Note that during program shutdown using PL_cleanup(), all atoms and blobs are reclaimed as described above. These objects are reclaimed regardless of their registration count. The order in which the atoms or blobs are reclaimed under PL_cleanup() is undefined. However, when these objects are reclaimed using garbage_collect_atoms/0, registration counts are taken into account.
12.4.9.1 Defining a BLOB type
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_* */ const 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); int (*save)(atom_t a, IOSTREAM *s); atom_t (*load)(IOSTREAM *s); ... } 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_TEXT
- If specifie