The e4_Marker class provides the abstraction of a persistent named marker. A marker is associated with a storage; the e4_Marker class provides a method to retrieve an instance of e4_Storage that represents the associated storage. A marker marks a specific node, its marked node. Each marker is identified by a name that is required to be unique within the containing storage; each marker is also identified by a unique integer identifier. The underlying marker representation is reference counted and its memory is freed automatically when the last reference to it is discarded.
More than one marker may mark a specific node. A node is reachable if it is marked by one or more markers, or if it is reachable from a marked node, recursively. The e4_Marker class provides methods to retrieve the marked node and to reuse this marker to mark another node.
Markers are not constructed directly by a user program. Instead, they are obtained from a storage, as follows:
If the GetMarker method call succeeds, m is assigned to the retrieved marker. Any number of markers can be held by a user program, limited only by available machine resources.e4_Storage s("mystorage", E4_METAKIT); ... e4_Marker m; ... if (!s.GetMarker("mymarker", m)) { printf("Could not get or create marker \"mymarker\"\n"); }
The e4_Marker class provides assignment and comparison operators. When one instance is assigned to another, they now refer to the same marker. The comparison operators allow a user program to determine whether two instances refer to the same marker:
The global variable invalidMarker refers to a constant instance of e4_Marker that is guaranteed to be invalid. You can assign this instance to a local e4_Marker variable to discard the reference to another marker it contains, as shown in the following example:e4_Marker m1, m2; ... if (!s.GetMarker("m1", m1)) { ... } m2 = m1; ... if (m1 == m2) { printf("They are one and the same.\n"); }
The assignment to m causes the reference count for the mymarker marker to drop to zero, and its memory is freed. Note that any modifications to mymarker are written to persistent storage only when its associated storage is committed. Remember to assign invalidMarker to instances of e4_Marker embedded within heap allocated structures before these structures are freed, to ensure that the reference count of markers referenced by the embedded instances is correct.e4_Marker m; ... if (!s.GetMarker("mymarker", m)) { ... } ... m = invalidMarker; if (m.IsValid()) { printf("Something fishy here!\n"); }
When the storage containing a marker is closed, any e4_Marker instances
referring to that marker become invalid. Instances may also become invalid
if the marker is deleted from its associated storage.
e4_Marker() | Default constructor. Returns an invalid marker. |
e4_Marker(const e4_Marker &ref) | Copying constructor. Returns a marker whose state is the same as ref. |
~e4_Marker() | Destructor. Decrements the reference count of the underlying marker; when that reference count reaches zero, the memory for the underlying marker representation is freed. |
bool operator==(const e4_Marker &comp) const | Returns true if comp refers to the same marker as this or if both are invalid, false otherwise. |
bool operator!=(const e4_Marker &comp) const | Returns true if comp does not refer to the same marker as this, false if they do refer to the same marker or both are invalid. |
e4_Marker & operator=(const e4_Marker &ref) | Copies the state of ref to this e4_Marker instance and returns this. |
const char *GetName() const | Returns the name with which this marker was created, or NULL if the marker is invalid. Note that the memory occupied by the returned string is owned by e4Graph and may be reused when another e4_Tree method is invoked. |
bool GetStorage(e4_Storage &s) const | Retrieves the storage associated with this marker in s and returns true, if the marker is valid. Returns false otherwise and s is not modified. |
bool GetMarkedNode(e4_Node &n) const | Retrieves the marked node of this marker in n and returns true, if the marker is valid. Returns false otherwise and n is not modified. |
bool SetMarkedNode(e4_Node n) | Sets the node marked by this marker to n. The node previously marked by this marker may now be unreachable. If so, its storage is deleted and it becomes invalid. Returns true upon success and modified the marked node. Upon failure, the marked node is not modified and false is returned. |
bool GetUniqueID(e4_MarkerUniqueID &muid) const | Retrieves in muid a type-safe unique identifier that uniquely identifies this marker within its associated storage and returns true. If this marker is invalid, returns false. Type-safe unique identifiers are described here. |
bool Delete() const | Deletes the physical storage occupied by this marker in its associated storage and recursively deletes nodes and vertices that become unreachable when this marker is deleted. Any instances of this marker or nodes and vertices that became unreachable become invalid. If the operation succeeds, returns true; otherwise returns false. The state of this marker is undefined if false is returned. |
bool IsValid() const | Returns true if this is a valid marker, false otherwise. |
bool SetUserData(int userData) const | Persistently associates the value of userData with this marker. This value is for use by application programs that incorporate e4Graph, and e4Graph itself does not use this value. The initial value, before it is set by application programs, is zero. |
bool GetUserData(int &userData) const | Retrieves the persistent user data associated with this marker. The user data is initialized to zero and may be set with SetUserData. |
e4_RefKind Kind() const | Returns E4_RKMARKER, the e4_RefKind identifier for e4_Marker. |