table of contents
other versions
other sections
tie(3tcl) | Tcl Data Structures | tie(3tcl) |
NAME¶
tie - Array persistenceSYNOPSIS¶
package require Tcl 8.4DESCRIPTION¶
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.- ::tie::tie arrayvarname options... dstype dsname...
- This command establishes a tie between the Tcl array whose
name is provided by the argument arrayvarname and the data
source identified by the dstype and its series of dsname
arguments. All changes made to the Tcl array after this command returns
will be saved to the data source for safekeeping (or distribution).
- varname arrayvarname (in)
- The name of the Tcl array variable to connect the new tie to.
- name|command dstype (in)
- This argument specifies the type of the data source we wish to access. The dstype can be one of log, array, remotearray, file, growfile, or dsource; in addition, the programmer can register additional data source types. Each dstype is followed by one or more arguments that identify the data source to which the array is to be tied.
- string dsname (in)
- The series of dsname arguments coming after the dstype identifies the data source we wish to connect to, and has to be appropriate for the chosen type.
- -open
- The Tcl array for the new tie is loaded from the
data source, and the previously existing contents of the Tcl array
are erased. Care is taken to not erase the previous contents should
the creation of the tie fail.
- -save
- The Tcl array for the new tie is saved to the
data source, and the previously existing contents of the data
source are erased.
- -merge
- Using this option prevents the erasure of any previously
existing content and merges the data instead. It can be specified in
conjunction with either -open or -save. They determine how
data existing in both Tcl array and data source, i.e duplicates,
are dealt with.
- ::tie::untie arrayvarname ?token?
- This command dissolves one or more ties associated with the
Tcl array named by arrayvarname. If no token is specified
then all ties to that Tcl array are dissolved. Otherwise only the tie the
token stands for is removed, if it is actually connected to the array.
Trying to remove a specific tie not belonging to the provided array will
cause an error.
- varname arrayname (in)
- The name of a Tcl array variable which may have ties.
- handle token (in)
- A handle representing a specific tie. This argument is optional.
- ::tie::info ties arrayvarname
- This command returns a list of ties associated with the Tcl array variable named by arrayvarname. The result list will be empty if the variable has no ties associated with it.
- ::tie::info types
- This command returns a dictionary of registered types, and the class commands they are associated with.
- ::tie::info type dstype
- This command returns the fully resolved class command for a type name. This means that the command will follow a chain of type definitions ot its end.
STANDARD DATA SOURCE TYPES¶
This package provides the six following types as examples and standard data sources.- log
- This data source does not maintain any actual data, nor persistence. It does not accept any identifying arguments. All changes are simply logged to stdout.
- array
- This data source uses a regular Tcl array as the origin of the persistent data. It accepts a single identifying argument, the name of this Tcl array. All changes are mirrored to that array.
- remotearray
- This data source is similar to array. The
difference is that the Tcl array to which we are mirroring is not directly
accessible, but through a send-like command.
- send tkname
- The Tcl array is in a remote interpreter and is accessed via Tk's X communication.
- comm::comm send hostportid
- The Tcl array is in a remote interpreter and is accessed through a socket.
- thread::send threadid
- The Tcl array is in a remote interpreter in a different thread of this process.
- file
- This data source uses a single file as origin of the
persistent data. It accepts a single identifying argument, the path to
this file. The file has to be both readable and writable. It may not
exist, the data source will create it in that case. This (and only
this) situation will require that the directory for the file exists and is
writable as well.
- growfile
- This data source is like file in terms of the
storage medium for the array data, and how it is configured. In constrast
to the former it however assumes and ensures that the tied array will
never shrink. I.e. the creation of new array entries, and the modification
of existing entries is allowed, but the deletion of entries is not, and
causes the data source to throw errors.
- dsource
- This data source uses an explicitly specified
data source object as the source for the persistent data. It
accepts a single identifying argument, the command prefix, i.e. object
command.
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.- ::tie::register dsclasscmd as dstype
- Using this command causes the tie framework to remember the
class command dsclasscmd of a data source class under the
type name dstype.
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- dsclasscmd objname ?dsname...?
- The first argument of the class command is the name of the
data source object to create. The framework itself will always
supply the string %AUTO%, to signal that the class command has to
generate not only the object, but the object name as well.
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.- ds destroy
- This method is called when the object ds is destroyed. It now has to release all its internal resources associated with the external data source.
- ds names
- This command has to return a list containing the names of all keys found in the data source the object talks to. This is equivalent to array names.
- ds size
- This command has to return an integer number specifying the number of keys found in the data source the object talks to. This is equivalent to array size.
- ds get
- This command has to return a dictionary containing the data found in the data source the object talks to. This is equivalent to array get.
- ds set dict
- This command takes a dictionary and adds its contents to the data source the object talks to. This is equivalent to array set.
- ds unset ?pattern?
- This command takes a pattern and removes all elements whose keys matching it from the data source. If no pattern is specified it defaults to *, causing the removal of all elements. This is nearly equivalent to array unset.
- ds setv index value
- This command has to save the value in the data
source the object talks to, under the key index.
- ds unsetv index
- This command has to remove the value under the key
index from the data source the object talks to.
- ds getv index
- This command has to return the value for the key index in the data source the object talks to.
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 SF Trackers [http://sourceforge.net/tracker/?group_id=12883]. Please also report any ideas for enhancements you may have for either package and/or documentation.KEYWORDS¶
array, database, file, metakit, persistence, tie, untieCATEGORY¶
Programming toolsCOPYRIGHT¶
Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
1.1 | tie |