[ Non-logical Variables, Arrays, Bags, Shelves and Stores | Reference Manual | Alphabetic Index ]

name_to_handle(+Type, +Name, -Handle)

Obtain a handle for a named object
Type
One of the atoms 'record', 'shelf', 'store' or 'stream'
Name
The name of an object (atom or compound)
Handle
A variable that will be unified with a handle

Description

Some types of ECLiPSe objects can alternatively be referred to by a name (alias) or by anonymous handle. These include

record
see record_create/1 and local record/1 declaration
shelf
see shelf_create/2,3 and local shelf/1 declaration
store
see store_create/1 and local store/1 declaration
stream
see open/3,4

This predicate maps a name to a handle, i.e. it obtains an anonymous handle for an existing named object. This is needed when one wants to use generic operations (such as mutual exclusion or conditions for thread synchronisation) on the object, because the corresponding primitives accept only handles.

Note that for some types of object, Name can be a compound term. In those cases, only the functor (name/arity) of Name is important for the lookup.

Generally, alias names should be used sparingly, because they prevent automatic garbage collection of objects.

Modes and Determinism

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Fail Conditions

Fails if there is no visible object of type Type with name Name

Exceptions

(4) instantiation fault
Type or Name are uninstantiated
(5) type error
Type is not an atom
(5) type error
Name is not an atom or compound term

Examples


    % Get a handle for the current 'output' stream
    ?- name_to_handle(stream, output, H).
    H = $&(stream(1))
    Yes (0.00s cpu)


    % Declare a store and a record, then get handles:
    ?- local store(shed).
    Yes (0.00s cpu)

    ?- local record(foo/1).
    Yes (0.00s cpu)

    ?- name_to_handle(store, shed, H).
    H = 'STORE'(16'ccb67f50)
    Yes (0.00s cpu)

    ?- name_to_handle(shelf, shed, H).
    No (0.00s cpu)

    ?- name_to_handle(record, foo, H).
    No (0.00s cpu)

    ?- name_to_handle(record, foo(_), H).
    H = 'REC'(16'faa0efa0)
    Yes (0.00s cpu)
    

See Also

store / 1, local / 1, is_handle / 1, is_handle / 2