Class: TSharedAttribute

Declaration: Attribute.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAttribute

Inherited By:

None.

Purpose:

TSharedAttribute is the base class for all attributes that are surrogates for internal attributes. The only data member of this or any of its derived classes should be a pointer to an object that descends from TInternalAttribute.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

If the storage of an attribute is to be shared, then a new class must be derived from TSharedAttribute. Whenever a class is derived from TSharedAttribute, a corresponding class must be derived from TInternalAttribute.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TSharedAttribute::TSharedAttribute

TSharedAttribute ()
TSharedAttribute (const TSharedAttribute & anAttribute)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TSharedAttribute & anAttribute -The attribute to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TSharedAttribute::~TSharedAttribute

virtual ~ TSharedAttribute ()

Interface Category:

API.

Purpose:

Destructor. Internal attributes are reference counted with respect to the number of corresponding shared attributes. When a shared attribute is deleted, the reference count of the corresponding internal attribute is decremented by one. The internal attribute is deleted when its reference count hits zero.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::AdoptByManager

void AdoptByManager (TInternalAttribute * anAttribute, TStream * aStream =NIL)

Interface Category:

API.

Purpose:

Every constructor of a class derived from TSharedAttribute must allocate a new corresponding class derived from TInternalAttribute. The new internal attribute must be passed to the attribute manager by calling the non-virtual member function AdoptByManager. AdoptByManager tries to give the internal attribute to the attribute manager. If there is not an internal attribute equivalent to the one just created and passed in, the new attribute is adopted by the attribute manager. If an internal attribute exists in the attribute manager that is identical to the newly created internal attribute, then the newly created internal attribute is deleted, and the shared attribute's internal attribute pointer is adjusted to point to the pre-existing internal attribute. The test for checking to see if an internal attribute exists in the attribute manager that is identical to the newly created internal attribute uses the virtual IsEqual member function, which must be overridden by classes deriving from TInternalAttribute.

Calling Context:

AdoptByManager should be called whenever a new internal attribute is created, and it must be called within each constructor of classes derived from TSharedAttribute.

Parameters:

TInternalAttribute * anAttribute -The internal attribute to be passed to the attribute manager.
TStream * aStream =NIL -The stream that the internal attribute is being retrieved from.

Return Value:

None.

Exceptions:

Throws on exception if the category of the new internal attribute is invalid.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::GetName

virtual const TToken & GetName () const

Interface Category:

API.

Purpose:

Returns the name associated with the attribute.

Calling Context:

Called directly to get the name associated with an attribute.

Parameters:

Takes no parameters.

Return Value:

Returns the value returned by its internal attribute's GetName member function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::GetCategory

virtual const TToken & GetCategory () const

Interface Category:

API.

Purpose:

Returns the category associated with the attribute.

Calling Context:

Called directly to get the category associated with an attribute.

Parameters:

Takes no parameters.

Return Value:

Returns the value returned by its internal attribute's GetCategory member function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns the value returned by its internal attribute's Hash member function.

Calling Context:

Called directly to get the hash value identifying an attribute.

Parameters:

Takes no parameters.

Return Value:

Returns the value returned by its internal attribute's Hash member function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::operator=

TSharedAttribute & operator =(const TSharedAttribute & comesFrom)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called directly to assign one object to another compatible object.

Parameters:

const TSharedAttribute & comesFrom -The source object for the assignment.

Return Value:

A non-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: TSharedAttribute::operator==

bool operator ==(const TSharedAttribute & compareTo) const

Interface Category:

API.

Purpose:

Compares the internal attributes of the two shared attributes.

Calling Context:

Called directly to compare to attributes.

Parameters:

const TSharedAttribute & compareTo -The shared attribute that this attribute is to be compared to.

Return Value:

Returns true if the operator== member function returns true for the internal attributes of the two shared attributes.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::operator>>=

virtual TStream & operator >>=(TStream & toStream) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toStream -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: TSharedAttribute::operator<<=

virtual TStream & operator <<= (TStream & fromStream)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromStream -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: TSharedAttribute::GetInternalAttribute

TInternalAttribute * GetInternalAttribute () const

Interface Category:

API.

Purpose:

Returns a pointer to the internal attribute.

Calling Context:

Called directly to get a pointer to the internal attribute of a shared attribute.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the internal attribute.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Internal attributes are reference counted, and internal attributes should be considered immutable.

Member Function: TSharedAttribute::SetInternalAttribute

virtual void SetInternalAttribute (TInternalAttribute * internal, TStream * aStream =NIL)

Interface Category:

API.

Purpose:

Sets the internal attribute data member. First, the new and the old internal attribute pointers are compared. If they are the same, nothing is done. If they are not the same, then the reference count on the old one is decremented, and the reference count on the new one is incremented. If this member function is called during streaming, and an object's reference count hits zero, it is marked for deletion when the stream context goes away.

Calling Context:

This is a protected member function.

Parameters:

TInternalAttribute * internal -The new internal attribute.
TStream * aStream =NIL -The stream that was being used when this function was called.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedAttribute::IsEqual

virtual bool IsEqual (const MCollectible * anotherAttribute) const

Interface Category:

API.

Purpose:

Compares the names, categories, and data of the internal attributes of two shared attributes.

Calling Context:

Do NOT call this function directly. Use NamesAndValuesMatch to compare two attributes. The implementation of NamesAndValuesMatch uses this virtual IsEqual member function to determine equality.

Parameters:

const MCollectible * anotherAttribute -The shared attribute that this attribute is to be compared to.

Return Value:

Returns true if the two shared attributes have the same name and category and result of calling TInternalAttribute::IsEqual on their internal attributes is true.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When overriding IsEqual, first use the inherited member function TAttribute::NamesMatch to determine if the two objects have similar types.

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