[ 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

name_to_handle(+, +, -) is semidet

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,"17h3")
    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 = $&(record,"371bt3")
    Yes (0.00s cpu)