OEOwnedPtr

template<class T>
class OEOwnedPtr

Warning

C++ only class. This class is not visible in any other languages.

This class is a classic smart pointer used for automatically managing the dynamic memory allocated for the object T. Explicitly calling delete is generally frowned upon in modern C++ due to the propensity of explicit delete leading to resource leaks and crashes. Deleting memory should be handled more automatically by mechanisms like OEOwnedPtr and OESharedPtr.

OEOwnedPtr is designed to mimic the C++11 std::unique_ptr in functionality with some important differences.

The first and most obvious difference is that OEOwnedPtr will compile and work in non-C++11 compilers. This provides the convenience and safety of std::unique_ptr without having to wait for every OpenEye platform to support C++11. That means the following will compile on all OpenEye supported platforms:

struct Foo { };

struct BarOwnsFoo
{
  OEOwnedPtr<Foo> _owned;
  Foo *GetFoo() { return _owned; }
};

Note

Users are free to use C++11 features with the OpenEye toolkits in their own code. OpenEye will be slowly phasing in more support for C++11 features over many releases. For example, OEOwnedPtr has move constructors to allow for the following idiom to work in C++11 compilers:

OEOwnedPtr<Foo> MakeFoo()
{
  return OEOwnedPtr<Foo>(new Foo);
};

The second key difference between OEOwnedPtr and std::unique_ptr is whether const is maintained when accessing the object being pointed to. By default, in order to maintain compatibility with C, C++ allows non-const access to const pointers. By extension, this same rule applied to C++ smart pointers. This leads to very surprising behavior like the following:

struct Foo
{
  int _x;
  void AlterFoo() { _x = 1; }
};

struct BarOwnsFoo
{
  Foo *_foo;
  void AConstMethod() const { _foo->AlterFoo(); }
};

Even though AConstMethod is const, it isn’t actually logically const. The internals of the class are changing. This behavior may seem benign at first, but it has vast implications in a library seeking to be thread-safe. The const on a method implies that the method is thread-safe, especially in C++11. In order to enforce thread-safety at runtime, OEOwnedPtr maintains the “const’ness” of its accessor methods. Therefore, the following is actually a compile error:

struct Foo
{
  int _x;
  void AlterFoo() { _x = 1; }
};

struct BarOwnsFoo
{
  OEOwnedPtr<Foo> _foo;
  void AConstMethod() const { _foo->AlterFoo(); }
};

Catching thread-safety problems very early, at compilation, is highly desirable for OpenEye. Hence the reason to differ from the standard smart pointer semantics in this way.

Constructors

OEOwnedPtr()
OEOwnedPtr(T *ptr)

Default constructors the pointer to NULL. Or constructs a smart pointer around the pointer ptr.

OEOwnedPtr(OEOwnedPtr&& rhs)

Move constructor to safely transfer ownership of the underlying pointer from one OEOwnedPtr to another. This allows OEOwnedPtr to be usable in container objects like std::vector in C++11 compatible compilers.

operator=

OEOwnedPtr<T> &operator=(T *rhs)

Construct a smart pointer around the pointer ptr.

Warning

OEOwnedPtr does not have a copy constructor or assignment operator for very good reason. It does not know how to properly deep copy the pointer, or how to properly “share” the pointer among multiple users. If this behavior is desired, for example, to use a smart pointer inside an std::vector prior to C++11, use OESharedPtr instead.

OEOwnedPtr<T>& operator=(OEOwnedPtr<T>&& rhs)

Move assignment operator to work around the above warning message. This is only available in C++11 compatible compilers.

operator*

T &operator*()
const T &operator*() const

Dereference the smart pointer and return a reference to the held object while maintaining const correctness. Note, dereferencing a NULL pointer is undefined.

operator->

T *operator->()
const T *operator->() const

Access the pointer held by this smart pointer while maintaining const correctness.

operator T *

operator T *()

Implicit conversion to a pointer to T.

operator const T *

operator const T *() const

Implicit conversion to a pointer to const T.

Get

T *Get()
const T *Get() const

Access the pointer held by this smart pointer while maintaining const correctness.

Release

T *Release()

Returns the pointer owned by this smart pointer. The smart pointer will cease to “own” the pointer in question. The smart pointer will effectively become a NULL pointer.

Warning

The user is expected to delete the pointer, usually by passing to a different smarter pointer class immediately.