Handles — C Library Procedures

NAME

Tcl_HandleAlloc, Tcl_HandleFree, Tcl_HandleTblInit, Tcl_HandleTblRelease, Tcl_HandleTblUseCount Tcl_HandleWalk, Tcl_HandleXlate − Dynamic, handle addressable tables.

SYNOPSIS

#include <tclExtend.h>
void_pt
Tcl_HandleTblInit (handleBase, entrySize, initEntries)
int
Tcl_HandleTblUseCount (headerPtr, amount)
void
Tcl_HandleTblRelease (headerPtr)
void_pt
Tcl_HandleAlloc (headerPtr, handlePtr)
void
Tcl_HandleFree (headerPtr, entryPtr)
void_pt
Tcl_HandleWalk (headerPtr, walkKeyPtr)
void
Tcl_WalkKeyToHandle (headerPtr, walkKey, handlePtr)
void_pt
Tcl_HandleXlate (interp, headerPtr, handle)

ARGUMENTS

char∗handleBase(in) Base name for the handle, numeric entry number will be appended.

intentrySize(in) Size of the table entries, in bytes.

intinitEntries(in) Initial number of entries to allocate.

intamount(in) Amount to alter the use count by.

void_ptheaderPtr(in) Pointer to the header.

char∗handlePtr(out) The handle name is returned here. It must be large enough to hold the handle base name with a number appended.

Tcl_Interp∗interp(in) Interpreter to use for error reporting.

char∗handle(in) Name of handle to operate on.

void_ptentryPtr(in) Pointer to a handle table entry.

int∗walkKeyPtr(i/o) Key used to walk the table, initialize to -1 before the first call.

intwalkKey(in) Key returned from walking the table.

DESCRIPTION

The Tcl handle facility provides a way to manage table entries that may be referenced by a textual handle from Tcl code. This is provided for applications that need to create data structures in one command, return a reference (i.e. pointer) to that particular data structure and then access that data structure in other commands. An example application is file handles.

A handle consists of a base name, which is some unique, meaningful name, such as ‘file’ and a numeric value appended to the base name (e.g. ‘file3’). The handle facility is designed to provide a standard mechanism for building Tcl commands that allocate and access table entries based on an entry index. The tables are expanded when needed, consequently pointers to entries should not be kept, as they will become invalid when the table is expanded. If the table entries are large or pointers must be kept to the entries, then the the entries should be allocated separately and pointers kept in the handle table. A use count is kept on the table. This use count is intended to determine when a table shared by multiple commands is to be release.

Tcl_HandleTblInit creates and initialize a Tcl dynamic handle table. The specified initial number of entries will be allocated and added to the free list. The use count will be set to one.

Tcl_HandleTblUseCount alters the use count on a table and returns the new value. The use count has amount added to it, where amount may be positive, zero or negative. A zero value retrieves the current use count. This is normally used to increment the use count when multiple commands are sharing the table.

Tcl_HandleTblRelease decrements the use count on a table. If it becomes zero (or negative), the the table will be released. Note that no clean up is done on the table entry client supplied data. If clean up must be done, then Tcl_HandleTblUseCount can be used to decrement the use count. When it goes to zero, the table may be walked and then released. HeaderPtr is declared as ClientData so that the procedure may be passed as a command deletion procedure.

Tcl_HandleAlloc allocates an entry and associates a handle with it. The handle is returned to the buffer pointed to by handlePtr can then be used to access the entry. The buffer must be large enough to accommodate the base handle name with 2 to 4 digits appended along with a terminating null byte. A pointer is returned to the allocated entry. If Tcl_HandleFree has not been called since initialization, handles will be handed out sequentially from zero. This behavior is useful in setting up initial entries, such as “stdin” for a file table.

Tcl_HandleXlate translates a handle to a pointer to the corresponding table entry. If the handle is not allocated (open) or is invalid, NULL is returned and an error message is set in interp->result.

Tcl_HandleWalk walks through and finds every allocated entry in a table. Entries may be deallocated during a walk, but should not be allocated. Tcl_HandleWalk will return a pointer to the entry, or NULL if no more entries are available. The integer pointed to by walkKeyPtr should be set to ‘-1’ before the first call, and then the pointer passed to each subsequent call left unmodified.

Tcl_WalkKeyToHandle converts a walk key, as returned from a call to Tcl_HandleWalk into a handle.

Tcl_HandleFree frees a handle table entry.

KEYWORDS

handle, table, allocate