Author: Jacob at home #1

The tgraph::open Command

This Tcl command is used to open a storage. It takes one, two or three arguments:

>     package require tgraph
>     tgraph::open storage-name ?option val ...?

The storage name is a legal name for the e4Graph driver selected. The rest of the arguments are alternating option names and values. The following options are supported:

- -driver driver-name. The driver name defaults to "Metakit 2.4".
- -rwmode mode. The read-write mode defaults to "rw" which means the storage is opened for reading and writing.
- -commitatclose bool. If true, the storage is committed before closing it if there are any changes. The default setting is true.
- -opengc bool. If true, a garbage collection is performed when the storage is first opened, to recycle any remaining unreachable space. The default setting is true.
- -gcbeforecommit bool. If true, a garbage collection is performed before each commit. The default setting is true.
- -autogc bool. If true, a garbage collection is performed whenever the tgraph system determines that one or more nodes or vertices have become unreachable. The default setting is true. If many changes are applied to a storage over a short period of time, it is advantageous to delay garbage collection until all changes have been applied. Setting -autogc to false implements this option.
- -bigprealloc bool. If true, the tgraph system preallocates many nodes and vertices so that many new nodes and vertices can be created efficiently. The default setting is false, which means that fewer nodes and vertices are preallocated. This is a space-time tradeoff. When many new vertices and nodes are added to a storage over a short period of time, it is advantageous to set this option to true, so that the library efficiently preallocates space for many new entities.
- -compactatclose bool. If true, the tgraph library compacts the storage as much as possible while preserving its logical structure, when the storage is closed. This results in a smaller disk file or database. The default setting is false, which means that when the storage is closed, no compaction takes place. This is a space-time tradeoff. It might be advantageous to set this option to true for storages from which a large number of entities have been removed.

The tgraph::open command returns a Tcl object representing the new storage just opened. If a storage is opened multiple times, the same Tcl object is returned on subsequent calls to tgraph::open. The Tcl storage object can be used to operate on the e4Graph storage object.

Here is an example showing how to open an e4Graph storage from Tcl and save the returned object in a Tcl variable for future use.

>     set mystorage [tgraph::open foo.db]