c('PL_free_blob')

Documentation
- Reference manual
  - Foreign Language Interface
    - The Foreign Include File
      - BLOBS: Using atoms to store arbitrary binary data
        
        Accessing blobs
        
        PL_is_blob()
        
        PL_unify_blob()
        
        PL_put_blob()
        
        PL_new_blob()
        
        PL_get_blob()
        
        PL_blob_data()
        
        PL_free_blob()
- Packages

Availability:C-language interface function

bool 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.^{228This
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.

A released blob keeps its type, so blob/2 still reports it, but it is recognised by blob_released/1. The system does not call the type's write() or compare() callback for such a blob, as these would dereference the object that is gone; it writes as <Type>(freed) and is ordered by handle.

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.