Spec:o3tl/utilities/heap ptr

From Apache OpenOffice Wiki
Jump to: navigation, search

o3tl::heap_ptr<> - a Const-Transitive Smart Pointer Class

Specification Status
Author Nikolai Pretzell
Last Change 2007-07-11
Status finished

Abstract

heap_ptr<> is a const-transitive, non-copyable, C++ smart pointer class.

  • smart pointer: A class that holds a pointer to memory allocated on the heap. The destructor automatically deletes (deallocates) the memory.
  • const-transitive: In const heap_ptr<int> pX( new int(25) ); not only pX is const, but also the integer value it points to. This is useful for member variables of classes, because if the class administrates the heap memory, it is normally part of its state.
  • non-copyable: When copying pointers to heap-memory, there either must be a reference counting or the pointer must not be copyable to make sure, delete is called at the right time for the heap memory.

References

Reference Document Location (URL)
Product Requirement, RFE, Issue ID IssueZilla 76768
Test case specification Unit Tests in module o3tl/qa/test-heap_ptr.cxx
Coding Standards this class helps to implement http://wiki.services.openoffice.org/wiki/Cpp_Coding_Standards/GEN#RAII

Contacts

Role Name E-Mail Address
Developer Nikolai Pretzell np@openoffice.org
Quality Assurance Thorsten Behrens thb@openoffice.org
Documentation Nikolai Pretzell np@openoffice.org

Detailed Specification

Typical Use

// Example 1:
class SomeClass;

class WithMemberDataOnHeap
{
  public: 
    // ...
  private:
    heap_ptr<SomeClass> mpSomeDataOnHeap;
};

// Example 2:
{
    heap_ptr<XY> p(new XY);
    // ...

}   // object of class XY owned by p will be deleted here!

Member Functions

Function Precondition Semantic Postcondition
heap_ptr(T * pass_heapObject = 0) - The object pointed to by pass_heapObject is owned by this instance. It would be deleted, if ~heap_ptr() will be called immediately after. get() == pass_heapObject
~heap_ptr() - If previously: get() != 0, the object pointed to by get() is deleted now.
self & operator=(T * pass_heapObject) - Any previously owned object will be deleted.
pass_heapObject will be owned now instead.
If before the call: get() == pass_heapObject, nothing will happen.
get() == pass_heapObject
const T & operator*() const get() != 0 Returns a const reference to the owned object on the heap. returnvalue == *get()
T & operator*() get() != 0 Returns a reference to the owned object on the heap. returnvalue == *get()
const T * operator->() const - Returns a const pointer to the owned object on the heap. returnvalue == get()
T * operator->() - Returns a pointer to the owned object on the heap. returnvalue == get()
operator safe_bool() - Returns true (a value that is convertible to true), if get() != 0, else false (a value that is convertible to false). bool(returnvalue) == is()
void reset(T * pass_heapObject) - Any previously owned object will be deleted.
pass_heapObject will be owned now instead.
If before the call: get() == pass_heapObject, nothing will happen.
get() == pass_heapObject
T * release() - Returns a pointer to the heap object previously owned. This object will not be owned by this any more. get() == 0
void swap(self & io_other) - Objects owned by this and io_other are exchanged. -
bool is() const - Returns true, if get() != 0. -
const T * get() const - Returns a pointer to the owned heap object . -
T * get() - Returns a pointer to the owned heap object . -

Migration

Member data on the heap
This class should be the default for class members that are pointers to heap memory and are not shared with other instances, but administrated only by one object. Plain pointers, std::auto_ptr<> and non const-transitive pointers should be replaced, when refactoring.
RAII in function bodies
It can be used in new code, when using RAII for heap memory within a function body.
Personal tools