util/include/chre/util/unique_ptr.h

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef CHRE_UTIL_UNIQUE_PTR_H_
#define CHRE_UTIL_UNIQUE_PTR_H_

#include "chre/util/non_copyable.h"

namespace chre {

/**
 * Wraps a pointer to a dynamically allocated object and manages the underlying
 * memory. The goal is to be similar to std::unique_ptr, but we do not support
 * custom deleters - deletion is always done via memoryFree().
 */
template<typename ObjectType>
class UniquePtr : public NonCopyable {
 public:
  /**
   * Construct a UniquePtr instance that does not own any object.
   */
  UniquePtr();

  /**
   * Constructs a UniquePtr instance that owns the given object, and will free
   * its memory when the UniquePtr is destructed.
   *
   * @param object Pointer to an object allocated via memoryAlloc. It is not
   *        valid for this object's memory to come from any other source,
   *        including the stack, or static allocation on the heap.
   */
  UniquePtr(ObjectType *object);

  /**
   * Constructs a new UniquePtr via moving the Object from another UniquePtr.
   *
   * @param other UniquePtr instance to move into this object
   */
  UniquePtr(UniquePtr<ObjectType>&& other);

  /**
   * Deconstructs the object (if necessary) and releases associated memory.
   */
  ~UniquePtr();

  /**
   * Determines if this UniquePtr owns an object, or references null.
   *
   * @return true if get() returns nullptr
   */
  bool isNull() const;

  /**
   * @return A pointer to the underlying object, or nullptr if this object is
   *         not currently valid.
   */
  ObjectType *get() const;

  /**
   * Releases ownership of the underlying object, so it will not be freed when
   * this object is destructed. After this function returns, get() will return
   * nullptr.
   *
   * @return A pointer to the underlying object (i.e. what get() would return
   *         prior to this function call)
   */
  ObjectType *release();

  /**
   * @return A pointer to the underlying object.
   */
  ObjectType *operator->() const;

  /**
   * @return A reference to the underlying object.
   */
  ObjectType& operator*() const;

  /**
   * @param index The index of an object in the underlying array object.
   * @return A reference to the underlying object at an index.
   */
  ObjectType& operator[](size_t index) const;

  /**
   * Move assignment operator. Ownership of this object is transferred and the
   * other object is left in an invalid state.
   *
   * @param other The other object being moved.
   * @return A reference to the newly moved object.
   */
  UniquePtr<ObjectType>& operator=(UniquePtr<ObjectType>&& other);

 private:
  //! A pointer to the underlying storage for this object.
  ObjectType *mObject;
};

/**
 * Allocates and constructs a new object of type ObjectType on the heap, and
 * returns a UniquePtr that owns the object. This function is similar to
 * std::make_unique.
 *
 * @param args The arguments to pass to the object's constructor.
 */
template<typename ObjectType, typename... Args>
UniquePtr<ObjectType> MakeUnique(Args&&... args);

}  // namespace chre

#include "chre/util/unique_ptr_impl.h"

#endif  // CHRE_UTIL_UNIQUE_PTR_H_