[ Type Testing | Reference Manual | Alphabetic Index ]

# is_handle(?Term, -Kind)

Succeeds if Term is an object handle of kind Kind

Term
  Prolog term.
Kind
  Atom or variable

## Description

Used to test whether Term is an object handle, and of what kind. Handles are references to anonymous ECLiPSe objects or to external data created via the foreign language interfaces. Handles are anonymous and are distinct from from the regular Prolog-style data types (number, atom, compound). They support only a limited number of operations, and are mostly used in relation to ECLiPSe's non-logical features.

The following kinds of object are defined by ECLiPSe itself:

bag
  A bag object, as created by bag_create/1.
engine
  An engine object, as created by engine_create/2.
record
  A record object, as created by record_create/1.
shelf
  A shelf object, as created by shelf_create/2,3.
store
  A store object, as created by store_create/1.
stream
  A stream object, as created by open/3,4, socket/3, etc.
[]
  A stale handle, no longer referring to any object, e.g. after handle_close/1, close/1, bag_dissolve/1.

Handles can be also be created by external predicates using the ECLiPSe C or C++ API. The kind of such a handle is determined by the atomic name returned by the user-defined kind() method.

### Modes and Determinism

- is_handle(?, -) is semidet

### Fail Conditions

Fails if Term is not an external data handle

## Examples

        ?- bag_create(B), is_handle(B, Kind).
        B = $&(bag,"371bnb")
        Kind = bag
        Yes (0.00s cpu)

        ?- engine_self(E), is_handle(E, Kind).
        E = $&(engine,"cg51thx4p")
        Kind = engine
        No (0.00s cpu)

        ?- get_stream(output, S), is_handle(S, Kind).
        S = $&(stream,1)
        Kind = stream
        No (0.00s cpu)

        ?- is_handle(42, Kind).
        No (0.00s cpu)

        ?- is_handle(output, Kind).
        No (0.00s cpu)

## See Also

is_handle / 1, handle_close / 1, type_of / 2, xget / 3, xset / 3