12.4.10.2 Accessing blobs

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.

int PL_is_blob(term_t t, PL_blob_t **type)

Succeeds if t refers to a blob, in which case type is filled with the type of the blob.

int PL_unify_blob(term_t t, void *blob, size_t len, PL_blob_t *type)

Unify t to a blob constructed from the given data and associated with the given type. This performs the following steps:

1. If the type has PL_BLOB_UNIQUE set, search the blob database for a blob of the same type with the same content. If found, unify t with the existing handle.
2. If not found or PL_BLOB_UNIQUE is not set, create a new blob handle. If PL_BLOB_NOCOPY is set, associate it to the given memory; else, copy the memory to a new area owned by the blob. Call the acquire() function of the type.
3. Unify t with the existing or new handle. This succeeds if t is already bound to the existing blob handle. If t is a variable, it succeeds if sufficient resources are available to perform the unification; if t is bound to something else, this fails.

It is possible that a blob referencing critial resources is created after which the unification fails. Typically these resources are eventually reclaimed because the new blob is not referenced and reclaimed by the atom garbage collector. As described with the release() function, it can be desirable to reclaim the critical resources after the failing PL_unify_blob() call.

int PL_put_blob(term_t t, void *blob, size_t len, PL_blob_t *type)

Store the described blob in t. The return value indicates whether a new blob was allocated (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().

atom_t PL_new_blob(void *blob, size_t len, PL_blob_t *type)

Create a blob from its internal opaque form. This function is intended for the “load” function of a blob.

int PL_get_blob(term_t t, void **blob, size_t *len, PL_blob_t **type)

If t holds a blob or atom, get the data and type and return TRUE. Otherwise return FALSE. Each result pointer may be NULL, in which case the requested information is ignored.

void * PL_blob_data(atom_t a, size_t *len, PL_blob_t **type)

Get the data and type associated to a blob. This function is mainly used from the callback functions described in section 12.4.10.1. Note that if the release() hook is called from PL_cleanup(), blobs are released regardless of whether or not they are referenced and the order in which blobs are released is undefined (the order depends on the ordering in the atom hash table). PL_blob_data() may be called safely on a blob that has already been released. If this happens during PL_cleanup() the return value is guaranteed to be NULL. During normal execution it may return the content of a newly allocated blob that reuses the released handle.

int PL_free_blob(atom_t blob)

New in 9.1.12. This function may be used on blobs with the PL_BLOB_NOCOPY flag set and the blob type implements the release() callback. It causes the release() callback to be called, after which the data and size are set to 0 if the release() returns TRUE. After this sequence, the release() for this blob is never called again. The related atom_t handle remains valid until it is no longer referenced and reclaimed by the atom garbage collector. If the blob data is accessed using e.g., PL_get_blob() it returns NULL for the data and 0 for the size.^{226This means that any predicates or callbacks that use the blob must check the result of PL_blob_data().} If the release() function is not called, or if it returns FALSE, FALSE is returned.

PL_free_blob() may be called multiple times on the same atom_t, provided the handle is still valid. Subsequent calls after a successful call have no effect and return FALSE.