gk::environment

Shared tree-based data structure

Synopsis

gk::environment ?options? envName

Description

The gk::environment command creates a new instance of an environment, a tree-based data structure that can optionally be shared between GroupKit processes. Environments are pervasive in GroupKit, and are used to store a wide variety of data.

Environments store data in a tree structure. Nodes in the tree are referred to by a key, using a period as a hierarchy delimeter. For example "users.3.color" refers to a node called "color" which is a child of a node called "3" which is a child of a node called "users" which is a child of the root of the tree. Any node can contain zero or more children. One feature of environments is that nodes can contain either data or children, but not both.

Three options can be specified when the environment is created if the environment is to be shared. Specifying "-server" creates a centralized environment that other processes can connect to. The "-client" option is used to connect to a previously created centralized environment. Finally, the "-peer" option can be used to specify a replicated sharing strategy, commonly used in GroupKit conference processes.

Environments also generate events when their contents changes; these events are similar to those implemented by the gk::event command. As well, there is a mechanism to extend the behavior of environments by adding new operations or redefining existing ones.

Environment Command

The gk::environment command creates a new Tcl command named envName, which is used to work with the environment. It supports a number of different operations:

envName set key value

Place the given value into the node key. If the node does not exist, it is created, along with all intermediate nodes. If the node previously stored data, that data is replaced. If the node previously had any children, all child nodes are deleted.

envName get key

Return the value associated with the node. If the node does not exist, an empty string is returned. If the node does not hold data but instead has child nodes, a complex representation of all the children and their data (based on Extended Tcl's keyed lists) is returned.

envName exists key

Returns 1 if the given node exists in the environment, 0 otherwise.

envName delete key

Delete a particular node in the environment, and any children of that node.

envName keys ?key?

Return a list of all the children of the given node. If the node does not exist or has no children, the empty list is returned. If key is omitted the list of all children of the root of the environment are returned.

envName destroy

Destroy the environment data structure and its associated Tcl command.

envName bind event script

Create a new event binding such that when the environment generates event, script will be executed. This command returns an event binding id. See the section on "Event Bindings" for details on the events that are generated and their parameters.

envName delbind binding

Delete a previously created event binding.

envName export

Dump the entire contents of the environment into a single string that can be passed to the "import" command.

envName import data

Load the contents of the environment from a string which was generated by the "export" command.

envName debug key

Provide a reader-friendly version of the environment's contents.

envName option operation ?args?

Environments actually support two complete hiearchies, the normal "data" hierarchy, and a second "option" hierarchy, which is typically used to store information controlling how the environment behaves. The "option" command is used to access this subtree. Available operations (which parallel those in the data hierarchy are):

envName option set key value
envName option get key
envName option delete key
envName option exists key
envName option keys ?key?

envName command operation ?args?

When an environment command (e.g. "envName set") is invoked, the particular operation ("set") is looked up in an internal table to determine how to perform that operation. Using the "command" operation of environments, it is possible to manipulate that table, thereby adding new commands to the environment or replacing existing ones. Handlers for these operations are either C built-ins or Tcl procedures; the latter are called with the name of the environment, the operation, and any additional parameters as arguments. Additionally, a list of "routings" for shared environments can be specified.

envName command set subcmd script

Specify script as the handler for the environment operation specified by subcmd.

envName command get subcmd

Return the name of the handler for subcmd. This will either be the name of the Tcl procedure, or "<builtin>" for C handlers.

envName command delete subcmd

Delete the operation subcmd from the environment.

envName command list

Return a list of all known subcommands of the environment.

envName command rename subcmd newsubcmd

Rename the given subcmd so that it is now referred to by the name newsubcmd.

envName command routing subcmd ?routings?

Specify a list of routings for this command, or return the current list of routings. Routings are used by shared environments to control how environment messages are distributed among processes.

envName addDependent key process ?type?

For shared environments, the "addDependent" command provides a mechanism to specify that a particular node in the environment is dependent on the existence of a GroupKit process, and that when that process goes away, the corresponding node should be deleted. The optional type specifies whether the node is part of the "data" hierarchy, or the "option" hierarchy.

Event Bindings

Environments generate events when nodes are changed. These are similar to those generated by the gk::event command, but environment events are intercepted by the bind environment command.

When a node is added to the environment, an "addEnvInfo" event is generated. Its parameter is "%K" specifying the key of the node that is added. When an existing node is changed, a "changeEnvInfo" event is generated, again with a "%K" parameter. When a node is deleted, a "deleteEnvInfo" is generated, again with a "%K".

As well, a second event is generated, named after the node affected. For example if you add a node "users.3.color", an event named "users.3.color" will be generated. This allows you to bind on particular nodes. Remember also that event bindings support wildcards, so you could bind on "users.*.color". This feature lets you design bindings without worrying about a lot of parsing code to determine if you have the right event. For these types of events, parameters are "%K" (the key), "%V" (the value at the key), "%P" (the previous value), "%O" (the operation; one of addEnvInfo, changeEnvInfo or deleteEnvInfo) and "%1" through "%9" for each dot separated component of the key (e.g. "%3" would be "color" in the example).