e4Graph Constants and Enumerations
Author: Jacob Levy

Enumerations Defined by the e4Graph Package

The e4_ReleaseStatus enumeration defines identifiers representing the possible release status values for a release of e4Graph:

>     typedef enum e4_ReleaseStatus {
>         E4_ALPHARELEASE = ...,
>         E4_BETARELEASE,
>         E4_FINALRELEASE,
>         E4_PATCHRELEASE
>     } e4_ReleaseStatus;

The e4_VertexType enumeration defines the possible types for a vertex value in e4Graph:

>     typedef enum e4_VertexType {
>         E4_VTUNKNOWN = ...,
>         E4_VTNODE,
>         E4_VTINT,
>         E4_VTDOUBLE,
>         E4_VTSTRING,
>         E4_VTBINARY
>     } e4_VertexType;

E4_VTNODE denotes that the vertex contains a node value, E4_VTINT means the vertex contains an integer value, E4_VTDOUBLE denotes that the vertex contains a 64-bit floating point value, E4_VTSTRING means the vertex contains a NULL terminated string value, and E4_VTBINARY denotes that the vertex contains a binary uninterpreted value of arbitrary size. E4_VTUNKNOWN serves as an illegal value to returns when an invalid vertex is asked for its type.

The e4_RefKind enumeration defines constants that identify the various entities of an e4Graph storage. These constants are returned by the Kind() method of each entity. You can use these to identify the type of the entity if you only know the type as e4_RefCount, the base type for all entities.

>     typedef enum e4_RefKind {
>         E4_RKINVALID = ...,
>         E4_RKSTORAGE,
>         E4_RKNODE,
>         E4_RKVERTEX
>     } e4_RefKind;

The e4_InsertOrder enumeration defines the possible insertion orders of a vertex into a node:

>     typedef enum e4_InsertOrder {
>         E4_IONONE = ...,
>         E4_IOAT,
>         E4_IOFIRST,
>         E4_IOLAST,
>         E4_IOBEFORE,
>         E4_IOAFTER
>     } e4_InsertOrder;

E4_IOAT means the new vertex is inserted at the given rank. E4_IOFIRST and E4_IOLAST denote that the new vertex is inserted as the first or last vertex in a node, respectively. E4_IOBEFORE means the same as E4_IOAT. E4_IOAFTER means that the new vertex is inserted so that it becomes the vertex immediately following the vertex with the given rank. E4_IONONE serves an an illegal value.

The e4_VisitMethod enumeration defines the possible methods for a vertex visitor to visit its selection of vertices:

>     typedef enum e4_VisitMethod {
>         E4_VMUNKNOWN  = ...,
>         E4_VMSTORAGE,
>         E4_VMNODE,
>         E4_VMNODERANDOM
>     } e4_VisitMethod;

E4_VMSTORAGE means that this vertex visitor will visit all vertices in a given storage in some implementation dependent order. E4_VMNODE means that the vertices of a given node will be visited in rank order. E4_VMNODERANDOM means that the vertices of a given node will be visited in some implementation dependent order. E4_VMUNKNOWN serves as an illegal value.

The e4_DetachChoice enumeration defines the possible choices for whether to visit detached, attached or both kinds of nodes and vertices:

>     typedef enum e4_DetachChoice {
>         E4_DCDETACHED  = ...,
>         E4_DCATTACHED,
>         E4_DCBOTH
>     } e4_DetachChoice;

E4_DCDETACHED means that the visitor will visit only detached entities. E4_DCATTACHED means that the visitor will visit only attached entities; in the case of a node visitor, it will also visit the root node, even if that node is detached. E4_DCBOTH means that the visitor will visit both detached and attached entities in this storage.

The following two enumerations define types used by e4_Storage::GetStatistic. The e4_Space enumeration defines the various allocation spaces within a storage. Entities are allocated from these spaces to represent stored values:

>     typedef enum e4_Space {
>         E4_SPNODE  = ...,
>         E4_SPVERTEX,
>         E4_SPNAME,
>         E4_SPSTRING,
>         E4_SPINT,
>         E4_SPDOUBLE,
>         E4_SPBINARY
>     } e4_Space;

The e4_SpaceStat enumeration defines the various kind of statistics collected about allocation within the allocation spaces in a storage:

>     typedef enum e4_SpaceStat {
>         E4_SSUSED  = ...,
>         E4_SSAVAIL,
>         E4_SSFREED,
>         E4_SSALLOC
>     } e4_SpaceStat;

The E4_SSUSED and E4_SSAVAIL statistics denote the number of slots used within a space, and the total number of slots available within that space, respectively. The E4_SSALLOC and E4_SSFREED statistics denote the number of slots used and freed, respectively, since the time the storage was opened in this process.

Structures Defined by e4Graph

The e4_Binary structure is used to pass around a binary uninterpreted value together with its size, in bytes:

>     typedef struct e4_Binary {
>         int nbytes;
>         void *bytes;
>     } e4_Binary;

The e4_Value structure is used to pass values from e4Graph methods when the type of the value is not known ahead of time. Accordingly, the e4_Value structure contains both the actual value and its type, and potentially also its size if the size can vary:

>     typedef struct e4_Value {
>         e_VertexType vertexType;
>         e4_Node n;
>         union {
>             int i;
>             double d;
>             char *s;
>             e4_Binary b;
>         } u;
>     } e4_Value;

The following enumeration defines the various reasons for a vertex modify callback. One of these values is passed as the third parameter to a callback function invoked when a vertex modify event is fired:

>     typedef enum e4_ModVertexEventReason {
>         E4_ERMVMODVALUE  = ...,
>         E4_ERMVRENAME,
>         E4_ERMVREPARENT,
>         E4_ERMVDETVERTEX,
>         E4_ERMVMODUSERDATA,
>     } e4_ModVertexEventReason;

The value E4_ERVMMODVALUE is passed when a vertex's value is modified. The value E4_ERMVRENAME is passed when a vertex is renamed. The value E4_ERMVREPARENT is passed when a vertex is moved from one node to another, or when a vertex becomes attached. The value E4_ERMVDETVERTEX is passed when a vertex becomes detached. The value E4_ERMVMODUSERDATA is passed when the user data associated with the vertex is modified.

The following enumeration defines the various reasons for a node modify callback. One of these values is passed as the third parameter to a callback function invoked when a node modify event is fired:

>     typedef enum e4_ModNodeEventReason {
>         E4_ERMNADDVERTEX  = ...,
>         E4_ERMNDETVERTEX,
>         E4_ERMNRENVERTEX,
>         E4_ERMNMOVVERTEX,
>         E4_ERMNINSVERTEX,
>         E4_ERMNMODUSERDATA
>     } e4_ModNodeEventReason;

The value E4_ERMNADDVERTEX is passed when a new vertex is added to the node. The value E4_ERMNDETVERTEX is passed when a vertex is detached from this node. The value E4_ERMNRENVERTEX is passed when the name of a vertex in this node is changed. The value E4_ERMNMOVVERTEX is passed when vertices in the node are reordered or when a vertex is moved out of or into the node. The value E4_ERMNINSVERTEX is passed when a vertex is moved into this node. The value E4_ERMNMODUSERDATA is passed when the user data associated with this node is modified.

Constants Defined by the e4Graph Package

The following constants can be OR-ed together and given as an argument to the e4_Storage constructor to define storage permissions:

E4_SPCOMMIT: If set, changes to the storage can be committed. If not set, attempts to commit the storage implicitly (e.g. at closing) are silently ignored, and calling Commit() returns false.

E4_SPMODIFY: If set, the storage is opened so that it can be modified by the user program. If this permission is not set, the storage is opened so that it can only be queried but not modified by the user program..

E4_SPINITIALIZE: If set, data structures to initialize a new storage can be created when the storage is opened. If the data structures need to be created and the permission is not set, the opening of the new storage will fail. Therefore you can only open existing storages when E4_SPINITIALIZE is not set.

E4_SPUPDATEFORMAT: If a storage was committed using an older version of e4Graph and with an older data format, some of the data may need to be reformatted to be usable by the current version of e4Graph. This is done automatically when such a storage is opened, if this permission is set. If reformatting is needed and the permission is not set, then the opening will fail.

E4_SPCOPYTO: If set, the storage can be used as the target of a call to e4_Storage::CopyTo. If not set, the storage cannot be used for that purpose.

E4_SPCOPYFROM: If set, the storage can be used as the source of a call to e4_Storage::CopyTo. If not set, it cannot be used for that purpose.

E4_SPDEFAULTMASK: This mask consists of E4_SPMODIFY, E4_SPCOMMIT, E4_SPINITIALIZE, E4_SPUPDATEFORMAT, E4_SPCOPYTO, and E4_SPCOPYFROM, OR-ed together.

The following constants can be OR-ed together and given as an argument to the e4_Storage constructor and e4_Storage::SetState() to set various behaviors:

E4_COMMITATCLOSE: If set, the storage is committed before it is closed. By default this mode is set.

E4_AUTOCOMMIT: If set, the storage is committed periodically when changes exist in the storage. This is not yet implemented. By default this mode is not set.

E4_OPENGC: If set, a garbage collection is performed when the storage is opened. By default this mode is set.

E4_GCBEFORECOMMIT: If set, a garbage collection is performed before every commit. By default this mode is off.

E4_AUTOGC: If set, a garbage collection is performed whenever an entity (node or vertex) becomes unreachable, to reclaim all newly unreachable space in the storage. If a large number of changes are applied to a storage, it is useful to delay garbage collection until all changes have been applied. Turning off this mode will achieve that effect. This mode is on by default.

E4_BIGPREALLOC: If set, space is preallocated in the storage in big increment. The default setting of this mode is off, causing the storage to preallocate space in relatively small increments. This mode is intended for when a large number of entities (nodes or vertices) are added to the storage. This mode optimizes the amount of work that e4Graph has to do to make space for new entities as they are added to the storage. This mode is off by default, causing preallocation to occur in small incrememts.

E4_COMPACTATCLOSE: If turned on, space is compacted when the storage is closed. This makes the storage as small as possible while preserving the logical structure of the data graph. This is not yet implemented. Off by default.

E4_NOVERTEXCACHE: If turned on, nodes in this storage do not cache vertex IDs. This might save some space but may make vertex lookup slower. Off by default, so that nodes in a storage do cache vertex IDs as they are discovered.

The following constants advise e4Graph on the desired caching behaviors for mappings of vertex names and vertex ranks to vertex IDs. This cache, per-node, significantly speeds up access to individual vertices given their name or rank. The cache management mechanism is explained here.

The constant E4_CACHEINCREMENTAL is the default value for the advisory caching policy. It means that information is cached only incrementally as it is discovered.

The constant E4_AUTOCACHENAMES advises e4Graph to always keep the mapping from vertex names to vertex IDs up to date for a node. This makes vertex lookup by name a much cheaper, constant overhead, operation. However if the cache is invalidated often by changes to the node, as explained here, then maintaining the cache up to date will be very expensive.

The constant E4_AUTOCACHERANKS advises e4Graph to always keep the mapping from vertex ranks to vertex IDs up to date for a node. This makes vertex lookup by rank a much cheaper, constant overhead, operation. However if the cache is invalidated often by changes to the node, as explained here, then maintaining the cache up to date will be very expensive.

The following are constants returned to indicate various error conditions:

The constant E4_VERTEXNOTFOUND is returned when a requested vertex is not found or an invalid vertex is used in an e4Graph operation.

The constant E4_NODENOTFOUND is returned when a requested node is not found or an invalid node is used in an e4Graph operation.

The constant E4_VERTEXNOTCREATED is returned when a vertex could not be created and the operation was supposed to return the rank of the new vertex.

The constant E4_NODENOTCREATED is returned when a node could not be created and the operation was supposed to return the raw unique identifier of the new node.

The following are some constants to be used as arguments to calls to the e4Graph library:

The constant E4_RANKNOTUSED should be passed by a caller of an e4Graph operation that takes a rank when the rank is meaningless and should not be used by that operation.

The following constants define bitfields that can be ORed together to define filtering masks for vertex visitors to select which vertices in their itinerary to visit and which ones to ignore. E4_VFNONE means that the visitor visits all vertices. ORing it with the other constants has no effect. E4_VFNAME means that only vertices whose name matches a given name should be visited. E4_VFTYPE denotes that only vertices whose type is the same as a given vertex type should be visited.

Storage drivers are selected by name when a storage is opened with an e4_Storage constructor. The constant string E4_METAKIT selects the Metakit storage driver that is included with the e4Graph package.

The constant E4_INVALIDUNIQUEID is used as the serial number stored in unique identifiers derived from e4_CommonUniqueID when the unique identifier is unassigned.

The following event codes are predefined by e4Graph:

Predefined event codes and their meaning:
E4_ECADDNODE | A node was added to the storage
E4_ECDETNODE | A node became detached
E4_ECATTNODE | A node became attached
E4_ECMODNODE | A node was modified
E4_ECADDVERTEX | A vertex was added to the storage
E4_ECDETVERTEX | A vertex became detached
E4_ECATTVERTEX | A vertex became attached
E4_ECMODVERTEX | A vertex was modified
E4_ECCCHANGESTG | The storage became stable or unstable
E4_ECOPENSTG | The storage was opened. This event's timestamp is recorded but the event is not reported via a callback
E4_ECCOPYTOSTG | This storage was used as the target of a CopyTo() operation. This event's timestamp is recorded but the event is not reported via a callback
E4_ECCOPYFRMSTG | This storage was used as the source of a CopyTo() operation. This event's timestamp is recorded but the event is not reported via a callback
E4_ECSETSTGROOT | The root node of this storage was set to some other node. This event's timestamp is recorded but the event is not reported via a callback
E4_ECCOMMITSTG | The storage was committed successfully (made stable). This event's timestamp is recorded but the event is not reported via a callback.

Additionally, the constant E4_ECMODSTORAGE is a bitmask that contains the event codes for all events that modify a storage. It can be used to retrieve the timestamp of the latest event that changed a storage, or to test whether any events modifying a storage have occurred since a given timestamp.

Global Variables Defined by the e4Graph Package

The global variable invalidStorage contains an invalid instance of e4_Storage. Use it to assign to a local variable of type e4_Storage to discard the reference to another storage it contains.

The global variable invalidNode contains an invalid instance of e4_Node. Use it to assign to a local variable of type e4_Node to discard the reference to another node it contains.

The global variable invalidVertex contains an invalid instance of e4_Vertex. Use it to assign to a local variable of type e4_Vertex to discard the reference to another vertex it contains.