[ Reference Manual | Alphabetic Index ]

# Recorded Database

The record-family of built-ins to store data across failures [more]

## Predicates

> current_record(?Key)
>   Succeeds if Key is the key of a recorded item.
> erase(+DBRef)
>   Succeeds if the database reference DBRef designates a term recorded in the record database and this term is successfully erased.
> erase(+Key, ?Value)
>   Succeeds if the term Value associated with key Key is removed as an entry from the record database.
> erase_all(+Key)
>   All the the values associated with key Key are removed from the record database.
> is_record(+Key)
>   Succeeds if Key is a key of a recorded item.
> local record(+Name)
>   Create a named record object
> record(+Key, ?Value)
>   Records the term Value after all other entries for key Key in the record database.
> record_create(-Handle)
>   Create an anonymous record handle
> record_wait_append(+Key, ?Value, +Timeout, +Max)
>   Variant of recordz/2, suitable for thread communication
> record_wait_remove(+Key, ?Value, +Timeout)
>   Variant of erase/2, suitable for thread communication
> recorda(+Key, ?Value)
>   Records the term Value before all other entries for key Key in the record database.
> recorda(+Key, ?Value, -DBRef)
>   Records the term Value before all other entries for key Key in the record database.
> recorded(+Key, ?Value)
>   Succeeds if the term Value has been recorded in the record database under the key Key.
> recorded(+Key, ?Value, -DBRef)
>   Succeeds if the term Value has been recorded in the record database under the key Key and DBRef is its unique reference.
> recorded_count(+Key, -Count)
>   Returns the number of entries under the record key
> recorded_list(+Key, -List)
>   Succeeds if the List is the list of all terms that are currently recorded in the record database under the key Key.
> recordz(+Key, ?Value)
>   Records the term Value after all other entries for key Key in the record database.
> recordz(+Key, ?Value, -DBRef)
>   Records the term Value after all other entries for key Key in the record database.
> referenced_record(+DBRef, -Value)
>   Succeeds if Value is the Term recorded under the database reference DBRef.
> rerecord(+Key, ?Value)
>   Erases all entries recorded under key Key and replaces them with the given value Value.

## Description

ECLiPSe provides several facilities to store information across backtracking. The following table gives an overview. If at all possible, the handle-based facilities (bags, records, shelves, stores) should be preferred because they lead to cleaner, reentrant code (without global state) and reduce the risk of memory leaks.

        Facility        Type            Reference       See
        ================================================================
        bags            unordered bag   by handle       bag_create/1
        ----------------------------------------------------------------
        anon.records    ordered list    by handle       record_create/1
        ----------------------------------------------------------------
        shelves         array           by handle       shelf_create/2,3
        ----------------------------------------------------------------
        stores          hash table      by handle       store_create/1
        ----------------------------------------------------------------
        named shelves   array           by name         shelf/2
        ----------------------------------------------------------------
        named stores    hash table      by name         store/1
        ----------------------------------------------------------------
        non-logical     single cell     by name         variable/1,2
        variables
        ----------------------------------------------------------------
        non-logical     array           by name         array/1,2
        arrays
        ----------------------------------------------------------------
        named records   ordered list    by name         record/1
        ----------------------------------------------------------------
        dynamic         ordered list    by name         dynamic/1,assert/1
        predicates
        ----------------------------------------------------------------

The record-facilities described in this section provide a non-logical form of storage (not subject to backtracking), organized conceptually as a list. Elements can be added at either ends of the list, while elements can be removed from any position in the list. The basic concept of this facility goes back to C-Prolog. ECLiPSe provides additional functionality in the form of anonymous record handles, and facilities for communicating between concurrent threads.

Generated from record.eci on 2022-09-03 14:26