Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

tie - Array persistence

Table Of Contents

SYNOPSIS

package require Tcl 8.5
package require tie ?1.2?

::tie::tie arrayvarname options... dstype dsname...
::tie::untie arrayvarname ?token?
::tie::info ties arrayvarname
::tie::info types
::tie::info type dstype
::tie::register dsclasscmd as dstype
dsclasscmd objname ?dsname...?
ds destroy
ds names
ds size
ds get
ds set dict
ds unset ?pattern?
ds setv index value
ds unsetv index
ds getv index

DESCRIPTION

The tie package provides a framework for the creation of persistent Tcl array variables. It should be noted that the provided mechanism is generic enough to also allow its usage for the distribution of the contents of Tcl arrays over multiple threads and processes, i.e. communication.

This, persistence and communication, is accomplished by tying) a Tcl array variable to a data source. Examples of data sources are other Tcl arrays and files.

It should be noted that a single Tcl array variable can be tied to more than one data source. It is this feature which allows the framework to be used for communication as well. Just tie several Tcl arrays in many client processes to a Tcl array in a server and all changes to any of them will be distributed to all. Less centralized variants of this are of course possible as well.

USING TIES

TIE API

This section describes the basic API used to establish and remove ties between Tcl array variables and data sources. This interface is the only one a casual user has to be concerned about. The following sections about the various internal interfaces can be safely skipped.

STANDARD DATA SOURCE TYPES

This package provides the six following types as examples and standard data sources.

CREATING NEW DATA SOURCES

This section is of no interest to the casual user of ties. Only developers wishing to create new data sources have to know the information provided herein.

DATA SOURCE OBJECTS

All ties are represented internally by an in-memory object which mediates between the tie framework and the specific data source, like an array, file, etc. This is the data source object.

Its class, the data source class is not generic, but specific to the type of the data source. Writing a new data source requires us to write such a class, and then registering it with the framework as a new type.

The following subsections describe the various APIs a data source class and the objects it generates will have to follow to be compatible with the tie framework.

Data source objects are normally automatically created and destroyed by the framework when a tie is created, or removed. This management can be explicitly bypassed through the usage of the "dsource" type. The data source for this type is a data source object itself, and this object is outside of the scope of the tie framework and not managed by it. In other words, this type allows the creation of ties which talk to pre-existing data source objects, and these objects will survive the removal of the ties using them as well.

REGISTERING A NEW DATA SOURCE CLASS

After a data source class has been written it is necessary to register it as a new type with the framework.

DATA SOURCE CLASS

Each data source class is represented by a single command, also called the class command, or object creation command. Its syntax is

DATA SOURCE OBJECT API

Please read the section DATA SOURCE CLASS first, to know how to generate new object commands.

Each object command for a data source object has to provide at least the methods listed below for proper inter-operation with the tie framework. Note that the names of most of the methods match the subcommands of the builtin array command.

And here a small table comparing the data source methods to the regular Tcl commands for accessing an array.

Regular Tcl             Data source
-----------             -----------
array names a           ds names
array size  a           ds size
array get   a           ds get
array set   a dict      ds set   dict
array unset a pattern   ds unset ?pattern?
-----------             -----------
set a($idx) $val        ds setv   idx val
unset a($idx)           ds unsetv idx
$a($idx)                ds getv   idx
-----------             -----------

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category tie of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

KEYWORDS

array, database, file, metakit, persistence, tie, untie

CATEGORY

Programming tools

COPYRIGHT

Copyright © 2004-2021 Andreas Kupries