A '''handle''' is a value that refers to some resource maintained by a system.



** See Also **

   [Abstract Data Types]:   includes a discussion of various data types, including handles

   [tcl handles]:   

   [transparent]:   a value that contains all the information necessary to generate the internal representation, such as a `[string]`, `[list]`, or `[dict]`



** Description **

In Tcl, handles are simply names that are used to identify a particular
resource maintained by some subsystem. Here is one example:

======
set chan [open /etc/motd r]
======

The value returned by `[open]` is a handle that identifies a specific [channel]
to commands like `[read]`. It is an '''opaque handle ''' because there is no
way to use the value to directly manipulate whatever it refers to.

Because of the Tcl data model in which [EIAS%|%everything is a string], handles
are pervasive.  Tcl provides a number of types of objects that are manipulated
at the script level via a handle:

   [array%|%arrays]:    

   [chan%|%channels]:   

   [command%|%commands]:   The name of a [command%|%command] is used by Tcl to locate the command to execute.  [oo::object%|%objects] are exposed as commands as well. 

   [interp%|%interpreters]:   

   [namespace%|%namespaces]:   

   [variable%|%variables]:   The name of a variable is used to indicate which variable to substitute.
   
   [coroutine%|%coroutines]:   
   
The names of all such Tcl objects are opaque handles:  They refer to things
that can not be directly accessed at script level. The purpose of an opaque
handle is to provide an
interface or reference to some facility while keeping the implementation
details out of view. It is a '''black box''', the contents of which a user of
the handle need not be concerned with.  This is particularly useful in Tcl
because a resource like a [channel] isn't really amenable to direct
representation as a value.  In contrast to values that are handles, other
values such as `[string]`, `[list%|%list]`, and `[dict]`, contain all the
information necessary to generate the correspondig internal representation.

Languages like [C] provide [pointer%|%pointers], which are handles to locations
in physical memory as through which values and data structures can be directly
dereferenced.  When this is undesirable, an opaque handle is implemented by
casting one [type] of structure to another type that has fewer members. The two
types have the same member layout at the beginning, but the additional members
of the full type are not available to the opaque type.  Higher-level languages
like Tcl do not provide direct handles to physical memory locations, but to
more logical [data structure%|%structures] and facilities.  To summarize, in
[C] a handle is used to access a resource directly, whereas in Tcl, a handle is
used to identify to a subsystem a resource which the subsystem then can access.

The closest that Tcl handles come to being references to data structures is
Tcl values themselves, to which are affixed an internal representation which
may indeed be some kind of data structure. For example, a `[list]`,
[EIAS%|%like all other values] in Tcl, is a string, and a command like
`[lindex]` generates an internal representation that [Tcl_Obj%|%gets attached]
to the list value. In this way every Tcl object can carry around with it an
internal representation that a command may manipulate.  Thus, ''every value is
an opaque handle''.

In Tcl, [object orientation%|%object] systems surface [class%|%classes] and
[instance%|%instances] as commands. The name of the command for an instance is
often stored in a variable, so there are actually three layers of handles in
this example:

======
$myobject mymethod
======

The first handle is `myobject`, which is the name of a variable, which is
"passed" to th `$` operator to retrieve a value.  The second handle is the
value, which is the name of a command.  The third handle is the command
itself, which is the interface to the instance.



** Page Authors **

   [NEM]:   

   [PYK]:   

   [AMG]:   

   [RFox]:   



<<categories>> Tutorial | Data Structure