Class: TGlobalID

Declaration: GlobalID.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TCollectibleGlobalID

Purpose:

A global ID is a machine-generated name that can be used to uniquely identify an object. Global IDs are probabistically unique across all tasks, all teams, and all machines, for all time. Global IDs are cheap to generate, and extremely cheap to use. Global IDs are designed to be treated like ordinary C++ objects. You can copy them, stream them, compare them for equality, and hash them. They are unique when they are constructed, so you can assign a unique ID to an object simply by including a global ID in its constructor. Use the special ID constructor for constant global IDs. This is handy for specifying things like an invalid object or all objects. The range of special IDs is purposefully kept small. Special only has to be unique for a particular population of IDs. For example, because models and links are not in the same population, special ID #1 can mean one thing for models and another thing for links. TGlobalID's member function, GetTextRepresentation, and the constructor, TGlobalID(const TText&), are used to convert the global ID to and from a text object. There are two general cases where this might be useful: (1) when registering global IDs with existing, text-based directory services. This includes File system directories and network name-binding protocols; (2) when debugging, to allow humans to manually transfer global IDs from one system to another.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Concurrency:

Not multithread safe.

Resource Use:

TGlobalID classes violate bitwise const in their implementation, which means that they cannot be placed into read-only memory.

Member Function: TGlobalID::TGlobalID

TGlobalID ()
TGlobalID (const TGlobalID &)
TGlobalID (SpecialIDValue)
TGlobalID (const TText &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Creates a special TGlobalID and initializes the identifier to the specified SpecialIDValue.
Creates a TGlobalID from the specified text object, thereby converting the text object into a global identifier. The text has to be a copy of the result returned by some call to TGlobalID::GetTextRepresentation. The exact format is private.

Calling Context:

Called by the stream-in operators.
Called to copy an object.
Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TGlobalID & -The object to be copied.
SpecialIDValue -The special ID for the new global ID.
const TText & -The text object from which to create the new global ID.

Return Value:

None.

Exceptions:

The fourth constructor throws kBadGlobalIDStringFormat if the format of the input string is invalid.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::operator=

TGlobalID & operator =(const TGlobalID &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TGlobalID & -The object to be copied.

Return Value:

Returns a const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::operator==

bool operator ==(const TGlobalID &) const

Interface Category:

API.

Purpose:

Tests whether the two objects are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGlobalID & -The object to be compared to this object.

Return Value:

Returns true if the two objects are equal; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::operator!=

bool operator != (const TGlobalID &) const

Interface Category:

API.

Purpose:

Tests whether the two objects are not equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGlobalID & -The object to be compared to this object.

Return Value:

Returns true if the two objects are not equal; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::Hash

long Hash () const

Interface Category:

API.

Purpose:

Returns the hash value for this global ID.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value for this global ID.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::operator>>=

TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::operator<<=

TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::IsSpecial

bool IsSpecial () const

Interface Category:

API.

Purpose:

Determines whether this global ID is special. Special global IDs can only be created by using the special ID constructor.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this is a special global ID; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGlobalID::GetTextRepresentation

void GetTextRepresentation (TText &) const

Interface Category:

API.

Purpose:

Converts this global ID to a text object. There are two general cases where this might be useful: (1) when registering global IDs with existing, text-based directory services. This includes File system directories and network name-binding protocols; (2) when debugging, to allow humans to manually transfer global IDs from one system to another.

Calling Context:

Call this function directly.

Parameters:

TText & -The text object into which to place the results of the conversion. This must be instantiated by the caller before invoking this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.