ICountedPointerTo
- Creates a templatized smart pointer with automatic reference counting.
ICountedPointerTo provides a smart C++ like pointer with this additional built-in behavior: when you create an instance of
ICountedPointerTo, it automatically calls IMRefCounted::addRef on the object pointed to; when the ICountedPointerTo is destroyed, it calls
IMRefCounted::removeRef to removes its reference to the object.
ICountedPointerTo also allows you to perform reference counting on
objects that do not descend from IMRefCounted. In this case,
it encloses, or wraps, the object in a reference-counted wrapper.
ICountedPointerTo - Member Functions and Data by Group
Constructors & Destructor
Use these functions to construct, copy, and destruct counted pointer objects.
- ~ICountedPointerTo
- Destroys the counted pointer.
public:
~ICountedPointerTo()
- This destructor destroys the counted pointer and decrements the reference count of the object pointed to.
When the count is zero, the object is deleted.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- ICountedPointerTo
- This function constructs an object of class ICountedPointerTo.
Overload 1
- Copies a counted pointer.
public:
ICountedPointerTo(const ICountedPointerTo < AType >& share)
- Use this constructor to create a copy of the given counted pointer.
The constructor increments the reference count of the object pointed to by the given counted pointer.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
- Construct a counted pointer object.
public:
ICountedPointerTo()
- Use this function to construct an object that points to nothing.
This function is slightly more efficient than calling ICountedPointerTo(0).
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 3
- Constructs an ICountedPointerTo that points to the given object.
public:
ICountedPointerTo(AType* adopt)
- Use this constructor to create an object of class ICountedPointerTo that points to the object specified by
the adopt parameter. This constructor adopts the given object and increments its reference count. Use the newly constructed instance
of ICountedPointer to make any further references to the object pointed to. Discard the raw pointer used to specify the
adopted object.
constructor.
- adopt
- A pointer to the object to be pointed to from the constructed object of class ICountedPointerTo.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Accessing an Object
Use these functions to access the pointer being counted.
- getAlias
- Returns a raw C++ pointer to the object to which this points.
public:
AType* getAlias() const
- This function returns a raw C++ pointer to the object to which this points.
If this pointer does not refer to an object, the function returns zero.
Use this function to pass a
raw C++ pointer to an existing function that expects one.
Do not continue to use the pointer after this ICountedPointerTo
object has been destroyed.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- operator *
- Returns a reference to the object pointed to.
public:
AType& operator *() const
- This operator returns a reference to the object referred to by the counted pointer.
- Exception
IInvalidRequest
| Thrown when your code attempts to dereference a null pointer.
|
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- operator ->
- Returns the object pointed to.
public:
AType* operator ->() const
- This operator is called when you use a counted pointer with the C++ class member access operator ->.
- Exception
An |
IInvalidRequest exception is thrown when your code attempts to dereference a null pointer. |
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Changing the Object Pointed to
Use these functions to point this counted pointer object at another object.
- operator =
- This operator modifies the counted pointer so that it refers to a different object from the one it currently points to.
Overload 1
- Changes the object pointed to.
public:
ICountedPointerTo < AType >&
operator =( const ICountedPointerTo < AType >& share )
Use this operator to modify the counted pointer so that it refers to the same
object as another counted pointer. If the object the pointer previously referred to was a valid object, that object's reference count is
decremented. When the count is zero, that object is deleted.
- share
- A counted pointer to the new target object.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
- Changes the object pointed to.
public:
ICountedPointerTo < AType >& operator =(AType* adopt)
- Use this operator to modify the counted pointer so that it refers to the given object to be adopted.
If the object the pointer previously referred to was a valid object, that object's reference count is
decremented. The object is deleted when its reference count is zero.
The function adopts the given object and increments its reference count. Make all further references to the
given object through this ICountedPointer object. Discard the raw pointer used to specify the adopted object.
- adopt
- The object to be pointed to. The operator assigns the adopted object to the instance of
ICountedPointerTo and increments the object's reference count.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Comparing and Testing the Pointer
Use these functions to determine whether this object points to a particular object or the same object that another
counted pointer object also points to, and whether the pointer is valid or not.
- operator !=
- This function determines whether the counted pointer refers to a particular object.
Overload 1
- Determines whether this pointer refers to the given object.
public:
bool operator !=(const AType* r) const
- Use this function to determine if this counted pointer refers to the given object.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
- Determines whether this pointer refers to the same object as another counted pointer.
public:
bool
operator !=( const ICountedPointerTo < AType >& r ) const
- Use this function to determine if this counted pointer refers to the same object as another counted pointer.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- operator ==
- This operator determines whether this pointer refers to a particular object.
Overload 1
- Determines whether this pointer refers to the same object as another counted pointer.
public:
bool
operator ==( const ICountedPointerTo < AType >& r ) const
- Use this operator to determine if this counted pointer refers to the same object as another counted pointer.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
- Determines whether this pointer refers to the given object.
public:
bool operator ==(const AType* r) const
- Use this function to determine if this counted pointer refers to the given object.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- valid
- Queries whether this counted pointer refers to a valid object.
public:
bool valid() const
- This function returns true if this counted pointer refers to a valid, non-null object. Otherwise it returns false.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- validate
- Asserts that this pointer refers to a valid object.
public:
void validate() const
- This function asserts that this counted pointer refers to a valid object. If it does not, the function throws
an exception.
- Exception
IInvalidRequest
|
This pointer does not refer to a valid object.
|
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Obtaining and Counting Object References
Use these methods to manage the reference count of an object.
- count
- Returns the current reference count.
public:
unsigned long count() const
- This function returns the reference count of the object to which
this counted pointer refers. If this counted pointer does not refer to a valid object, it returns
zero.
Note that when the counted pointer refers to an object that does not inherit from
IMRefCounted, this function returns the reference count of the
internal wrapper around that object
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
ICountedPointerTo - Inherited Member Functions and Data
Inherited Public Functions
- IMStreamable
-
- ICountedPointerTo
-
IMRefCounted* getCounted() const
void
in( AType* r,
IVoidMasterPointer* indirect,
IMRefCounted* )
void in(AType* r, IVoidMasterPointer* indirect, void*)
static bool isWrapped()
Inherited Public Data
Inherited Protected Functions
- IMStreamable
-
IMStreamable()
IMStreamable(const IMStreamable& other)
virtual void readFromStream(IDataStream& fromwhere) = 0
virtual void writeToStream(IDataStream& towhere) const = 0
Inherited Protected Data