The tgraph storage Object

The tgraph storage Object

The tgraph::open operation returns Tcl objects representing e4Graph storages. This page describes the operations supported by these Tcl objects. An object oriented style of programming is supported where the object returned from tgraph::open is used as the command name and the specific operation being invoked is the first argument.

The following operations on tgraph storage objects are supported:

$storage kind Returns "storage". Can be used to determine the type of tgraph object stored in the Tcl variable storage.

$storage configure Returns a list of alternating options and their current settings for the tgraph storage object. The list of legal options is defined here

$storage configure -option Returns the value of the configuration option option. The list of legal options is defined here

$storage configure ?-opt1 val1 ...? Sets new configuration options for this storage. Returns the previous set of configuration options. The list of legal options is defined here

$storage close The e4Graph storage represented by storage is closed and potentially all outstanding changes are committed, if the -commitatclose option is on.

$storage commit All outstanding changes to the e4Graph storage represented by storage are committed immediately.

$storage copyto otherstorage ?commit? Copies the e4Graph data from this storage to otherstorage. If the optional argument commit is present and true, then otherstorage is committed after the copy. After this operation, this storage and otherstorage contain exactly the same e4Graph data. All tgraph objects that used to belong to otherstorage become invalid.

$storage delete The e4Graph storage represented by storage is deleted. All tgraph objects that belong to the storage become invalid and cannot be used for subsequent commands.

$storage root
?node? If node is present and represents a valid tgraph node object in $storage then it becomes the new root node of the storage. If it is absent, this operation returns a tgraph node object that represents the current root node of the storage.

$storage isvalid Returns 1 if storage represents an open tgraph storage object and the e4Graph storage denoted by it is valid (has not been destroyed). Returns 0 if either of these conditions is not met.

$storage isdirty Returns 1 if there are outstanding uncommitted changes for the e4Graph storage object represented by storage, and 0 if a commit operation is not needed to save any changes.

$storage markdirty Marks the e4Graph storage represented by storage as having uncommitted outstanding changes. This is done automatically as needed by the implementation of the tgraph package, so you should rarely if ever need to call this operation.

$storage needsgc Returns 1 if the storage contains unreclaimed unreachable nodes or vertices.

$storage dogc Causes a garbage collection to be executed in the storage $storage. This call returns when the garbage collection has finished and after all detach events have fired.

$storage name Returns the name of the storage used in the tgraph::open operation that opened this storage.

$storage node Returns a tgraph node object representing a newly created detached node in $storage.

$storage vertex name val ?typesel? Returns a tgraph vertex object representing a newly created detached vertex in $storage. The vertex has the name name and value val. If the optional typesel is present, an attempt is made to convert val to the requested type before assigning to the newly created vertex.

$storage statistic space kind Returns a selected statistic measure about a specified allocation space within storage. The value of space can be marker, node, vertex, name, string, int, float, or binary, to select the corresponding allocation space. The value of kind can be used, available, freed, or allocated, to select the statistic measure gathered about allocation within that space.

$storage foreach node n ?-class c? cmd Evaluates cmd, a list of Tcl commands, once for each node in storage. While cmd is being evaluated, the Tcl variable n is bound to each node in turn. If the optional ?-class c? argument is absent, only attached nodes and the root node are visited. If c is both then both detached nodes and attached nodes are visited. If c is detached then only detached nodes are visited. If c is attached then only attached nodes and the root node are visited.

$storage foreach vertex v ?-class c? ?-type t? ?-name n? cmd Evaluates cmd, a list of Tcl commands, once for each vertex in storage. While cmd is being evaluated, the Tcl variable v is bound to each vertex in turn. If the optional argument -type t is present, only vertices in this storage with values of type t are visited. If the optional argument -name n is present, only vertices in this storage with the name n are visited. If the optional ?-class c? argument is absent, only attached vertices are visited. If the value of c is both then both attached and detached vertices are visited. If the value of c is detached then only detached vertices are visited. If c is attached then only attached vertices are visited.

$storage callback add elementtype eventtype cmd Registers cmd, a command prefix, to be called when the specified eventtype occurs on the given elementtype. The elementtype is one of node, or vertex. The eventtype is one of add, detach, or modify. The modify eventtype is valid only for elementtype vertex. When the event occurs on an element of the given type in this storage, the Tcl command name for that element is appended to cmd and the resulting string is invoked as a Tcl command.
For an explanation of callbacks, see the documentation of e4_Storage.
This command returns a token, denoted callbacktoken below, that can be used later to manipulate the registered callback.

$storage callback delete callbacktoken Removes a previously registered callback identified by the given callbacktoken. This is the callback token returned by a preceding callback add operation.

$storage callback get callbacktoken Retrieves the command prefix cmd registered for the callback identified by the given callbacktoken, a value returned by a preceding callback add operation.

$storage callback set callbacktoken newcmd Replaces the previously registered command prefix for callbacktoken with newcmd. The callbacktoken is a value returned by a preceding callback add operation.

$storage callback kind callbacktoken Returns a two element list containing the elementtype and eventtype for the callback that callbacktoken denotes, where callbacktoken is a value returned by a preceding callback add operation.

$storage callback count elementtype eventtype Returns the number of callbacks registered on this storage for the given elementtype and eventtype.

$storage callback exists elementtype eventtype Returns 1 if this storage has any callbacks registered for the given elementtype and eventtype and 0 otherwise.

$storage get elementtype id Returns the name of the Tcl command for the element identified by id and elementtype in this storage. The elementtype is one of node, or vertex. The given id must be the id of an element of the specified type in that storage, i.e. the same integer value as returned by the id operation on that element.

$storage share interp globalvar Makes this storage accessible in the slave interpreter interp as the value of the global variable globalvar. The storage stays accessible in this interpreter. You can close the storage in this interpreter to completely transfer exclusive access to the storage to interp.

Here is an example showing how to use a tgraph storage object to invoke operations on the underlying e4Graph storage object:

set mystorage [tgraph::open foo.db]
puts "The name of $mystorage is [$mystorage name]"
set myroot [$mystorage root]
...
$mystorage foreach node n {puts "$n: [$n vertexcount]"}
...
proc callback {pref node} {puts "Hello, $pref of $node"}
$mystorage callback add node add "callback addition"
set n [$myroot addnode foo last]
==> Hello, addition of t4Node0x578382ae33


$storage kind	Returns "storage". Can be used to determine the type of tgraph object stored in the Tcl variable storage.
$storage configure	Returns a list of alternating options and their current settings for the tgraph storage object. The list of legal options is defined here
$storage configure -option	Returns the value of the configuration option option. The list of legal options is defined here
$storage configure ?-opt1 val1 ...?	Sets new configuration options for this storage. Returns the previous set of configuration options. The list of legal options is defined here
$storage close	The e4Graph storage represented by storage is closed and potentially all outstanding changes are committed, if the -commitatclose option is on.
$storage commit	All outstanding changes to the e4Graph storage represented by storage are committed immediately.
$storage copyto otherstorage ?commit?	Copies the e4Graph data from this storage to otherstorage. If the optional argument commit is present and true, then otherstorage is committed after the copy. After this operation, this storage and otherstorage contain exactly the same e4Graph data. All tgraph objects that used to belong to otherstorage become invalid.
$storage delete	The e4Graph storage represented by storage is deleted. All tgraph objects that belong to the storage become invalid and cannot be used for subsequent commands.
$storage root ?node?	If node is present and represents a valid tgraph node object in $storage then it becomes the new root node of the storage. If it is absent, this operation returns a tgraph node object that represents the current root node of the storage.
$storage isvalid	Returns 1 if storage represents an open tgraph storage object and the e4Graph storage denoted by it is valid (has not been destroyed). Returns 0 if either of these conditions is not met.
$storage isdirty	Returns 1 if there are outstanding uncommitted changes for the e4Graph storage object represented by storage, and 0 if a commit operation is not needed to save any changes.
$storage markdirty	Marks the e4Graph storage represented by storage as having uncommitted outstanding changes. This is done automatically as needed by the implementation of the tgraph package, so you should rarely if ever need to call this operation.
$storage needsgc	Returns 1 if the storage contains unreclaimed unreachable nodes or vertices.
$storage dogc	Causes a garbage collection to be executed in the storage $storage. This call returns when the garbage collection has finished and after all detach events have fired.
$storage name	Returns the name of the storage used in the tgraph::open operation that opened this storage.
$storage node	Returns a tgraph node object representing a newly created detached node in $storage.
$storage vertex name val ?typesel?	Returns a tgraph vertex object representing a newly created detached vertex in $storage. The vertex has the name name and value val. If the optional typesel is present, an attempt is made to convert val to the requested type before assigning to the newly created vertex.
$storage statistic space kind	Returns a selected statistic measure about a specified allocation space within storage. The value of space can be marker, node, vertex, name, string, int, float, or binary, to select the corresponding allocation space. The value of kind can be used, available, freed, or allocated, to select the statistic measure gathered about allocation within that space.
$storage foreach node n ?-class c? cmd	Evaluates cmd, a list of Tcl commands, once for each node in storage. While cmd is being evaluated, the Tcl variable n is bound to each node in turn. If the optional ?-class c? argument is absent, only attached nodes and the root node are visited. If c is both then both detached nodes and attached nodes are visited. If c is detached then only detached nodes are visited. If c is attached then only attached nodes and the root node are visited.
$storage foreach vertex v ?-class c? ?-type t? ?-name n? cmd	Evaluates cmd, a list of Tcl commands, once for each vertex in storage. While cmd is being evaluated, the Tcl variable v is bound to each vertex in turn. If the optional argument -type t is present, only vertices in this storage with values of type t are visited. If the optional argument -name n is present, only vertices in this storage with the name n are visited. If the optional ?-class c? argument is absent, only attached vertices are visited. If the value of c is both then both attached and detached vertices are visited. If the value of c is detached then only detached vertices are visited. If c is attached then only attached vertices are visited.
$storage callback add elementtype eventtype cmd	Registers cmd, a command prefix, to be called when the specified eventtype occurs on the given elementtype. The elementtype is one of node, or vertex. The eventtype is one of add, detach, or modify. The modify eventtype is valid only for elementtype vertex. When the event occurs on an element of the given type in this storage, the Tcl command name for that element is appended to cmd and the resulting string is invoked as a Tcl command. For an explanation of callbacks, see the documentation of e4_Storage. This command returns a token, denoted callbacktoken below, that can be used later to manipulate the registered callback.
$storage callback delete callbacktoken	Removes a previously registered callback identified by the given callbacktoken. This is the callback token returned by a preceding callback add operation.
$storage callback get callbacktoken	Retrieves the command prefix cmd registered for the callback identified by the given callbacktoken, a value returned by a preceding callback add operation.
$storage callback set callbacktoken newcmd	Replaces the previously registered command prefix for callbacktoken with newcmd. The callbacktoken is a value returned by a preceding callback add operation.
$storage callback kind callbacktoken	Returns a two element list containing the elementtype and eventtype for the callback that callbacktoken denotes, where callbacktoken is a value returned by a preceding callback add operation.
$storage callback count elementtype eventtype	Returns the number of callbacks registered on this storage for the given elementtype and eventtype.
$storage callback exists elementtype eventtype	Returns 1 if this storage has any callbacks registered for the given elementtype and eventtype and 0 otherwise.
$storage get elementtype id	Returns the name of the Tcl command for the element identified by id and elementtype in this storage. The elementtype is one of node, or vertex. The given id must be the id of an element of the specified type in that storage, i.e. the same integer value as returned by the id operation on that element.
$storage share interp globalvar	Makes this storage accessible in the slave interpreter interp as the value of the global variable globalvar. The storage stays accessible in this interpreter. You can close the storage in this interpreter to completely transfer exclusive access to the storage to interp.