Provided by: tcllib_1.19-dfsg-2_all bug

NAME

       tie - Array persistence

SYNOPSIS

       package require Tcl  8.4

       package require tie  ?1.1?

       ::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.

       ::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).

              The  result  of  the  command  is always a token which identifies the new tie. This
              token can be used later to destroy this specific tie.

              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.

       The  command understands a number of additional options which guide the process of setting
       up the connection between Tcl array and data source.

              -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.

                     This option and the option -save exclude each other.  If  neither  this  nor
                     option -save are specified then this option is assumed as default.

              -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.

                     This option and the option -open exclude each other.  If  neither  this  nor
                     option -open are specified then option -open is assumed as default.

              -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.

                     When used with -open data in the  data  source  has  precedence.   In  other
                     words,  for  duplicates  the  data in the data source is loaded into the Tcl
                     array.

                     When used with -save data in the Tcl array has precedence. In  other  words,
                     for duplicates the data in the Tcl array is saved into the data source.

       ::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.

              It  should  be  noted that while severing a tie will destroy management information
              internal to the package the data source which was handled by the tie  will  not  be
              touched, only closed.

              After  the  command  returns none of changes made to the array will be saved to the
              data source anymore.

              The result of the command is an empty string.

              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.

              It accepts three identifying arguments, the  name  of  the  other  Tcl  array,  the
              command prefix for the send-like accessor command, and an identifier for the remote
              entity hosting the array, in this order. All changes are mirrored  to  that  array,
              via  the command prefix. All commands will be executed in the context of the global
              namespace.

              send-like means that the command prefix has to have send syntax and semantics. I.e.
              it  is  a  channel  over which we can send arbitrary commands to some other entity.
              The remote array data source however uses  only  the  commands  set,  unset,  array
              exists,  array  names,  array  set, and array get to retrieve and set values in the
              remote array.

              The command prefix and the entity id are separate to allow the data source  to  use
              options like -async when assembling the actual commands.

              Examples  of  command  prefixes,  listed  with the id of the remote entity, without
              options. In reality only the part before the id is the command prefix:

              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.

              All changes are saved in  the  file,  as  proper  Tcl  commands,  one  command  per
              operation. In other words, the file will always contain a proper Tcl script.

              If the file exists when the tie using it is set up, then it will be compacted, i.e.
              superfluous operations are removed, if the operations log  stored  in  it  contains
              either  at least one operation clearing the whole array, or at least 1.5 times more
              operations than entries in the loaded array.

       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.

              This restriction allows us to simplify both file format  and  access  to  the  file
              radically.  For  one,  the  file is read only once and the internal cache cannot be
              invalidated. Second, writing data is reduced to a simple append, and no  compaction
              step  is  necessary.  The  format of the contents is the string representation of a
              dictionary which can be incrementally extended forever at the end.

       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.

              To use this type it is necessary to know how the framework manages  ties  and  what
              data source objects are.

              All changes are delegated to the specified object.

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.

              After the call the argument dstype of the basic user command ::tie::tie will accept
              dstype  as a type name and translate it internally to the appropriate class command
              for the creation of data source objects for the new data source.

   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.

              This  is  followed  by  a  series  of arguments identifying the data source the new
              object is for. These are the same dsname arguments which are  given  to  the  basic
              user  command  ::tie::tie.  Their  actual  meaning  is dependent on the data source
              class.

              The result of the class command has to be the fully-qualified name of the new  data
              source object, i.e. the name of the object command.  The interface this command has
              to follow is described in the section DATA SOURCE OBJECT API

   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.

              The  result  of  the command is ignored. If an error is thrown then this error will
              show up as error of the set operation which caused the method call.

       ds unsetv index
              This command has to remove the value under the key index from the data  source  the
              object talks to.

              The  result  of  the command is ignored. If an error is thrown then this error will
              show up as error of the unset operation which caused the method call.

       ds getv index
              This command has to return the value for the key  index  in  the  data  source  the
              object talks to.

       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
       [http://core.tcl.tk/tcllib/reportlist].  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 (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>