include/lldb/Utility/CleanUp.h

//===-- CleanUp.h -----------------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_CleanUp_h_
#define liblldb_CleanUp_h_

#include "lldb/lldb-public.h"
#include <functional>

namespace lldb_utility {

//----------------------------------------------------------------------
// Templated class that guarantees that a cleanup callback function will
// be called. The cleanup function will be called once under the
// following conditions:
// - when the object goes out of scope
// - when the user explicitly calls clean.
// - the current value will be cleaned up when a new value is set using
//   set(T value) as long as the current value hasn't already been cleaned.
//
// This class is designed to be used with simple types for type T (like
// file descriptors, opaque handles, pointers, etc). If more complex
// type T objects are desired, we need to probably specialize this class
// to take "const T&" for all input T parameters. Yet if a type T is
// complex already it might be better to build the cleanup functionality
// into T.
//
// The cleanup function must take one argument that is of type T.
// The calback function return type is R. The return value is currently
// needed for "CallbackType". If there is an easy way to get around the
// need for the return value we can change this class.
//
// The two template parameters are:
//    T - The variable type of value that will be stored and used as the
//      sole argument for the cleanup callback.
//    R - The return type for the cleanup function.
//
// EXAMPLES
//  // Use with file handles that get opened where you want to close
//  // them. Below we use "int open(const char *path, int oflag, ...)"
//  // which returns an integer file descriptor. -1 is the invalid file
//  // descriptor so to make an object that will call "int close(int fd)"
//  // automatically we can use:
//
//  CleanUp <int, int> fd(open("/tmp/a.txt", O_RDONLY, 0), -1, close);
//
//  // malloc/free example
//  CleanUp <void *, void> malloced_bytes(malloc(32), NULL, free);
//----------------------------------------------------------------------
template <typename T, typename R = void> class CleanUp {
public:
  typedef T value_type;
  typedef std::function<R(value_type)> CallbackType;

  //----------------------------------------------------------------------
  // Constructor that sets the current value only. No values are
  // considered to be invalid and the cleanup function will be called
  // regardless of the value of m_current_value.
  //----------------------------------------------------------------------
  CleanUp(value_type value, CallbackType callback)
      : m_current_value(value), m_invalid_value(), m_callback(callback),
        m_callback_called(false), m_invalid_value_is_valid(false) {}

  //----------------------------------------------------------------------
  // Constructor that sets the current value and also the invalid value.
  // The cleanup function will be called on "m_value" as long as it isn't
  // equal to "m_invalid_value".
  //----------------------------------------------------------------------
  CleanUp(value_type value, value_type invalid, CallbackType callback)
      : m_current_value(value), m_invalid_value(invalid), m_callback(callback),
        m_callback_called(false), m_invalid_value_is_valid(true) {}

  //----------------------------------------------------------------------
  // Automatically cleanup when this object goes out of scope.
  //----------------------------------------------------------------------
  ~CleanUp() { clean(); }

  //----------------------------------------------------------------------
  // Access the value stored in this class
  //----------------------------------------------------------------------
  value_type get() { return m_current_value; }

  //----------------------------------------------------------------------
  // Access the value stored in this class
  //----------------------------------------------------------------------
  const value_type get() const { return m_current_value; }

  //----------------------------------------------------------------------
  // Reset the owned value to "value". If a current value is valid and
  // the cleanup callback hasn't been called, the previous value will
  // be cleaned up (see void CleanUp::clean()).
  //----------------------------------------------------------------------
  void set(const value_type value) {
    // Cleanup the current value if needed
    clean();
    // Now set the new value and mark our callback as not called
    m_callback_called = false;
    m_current_value = value;
  }

  //----------------------------------------------------------------------
  // Checks is "m_current_value" is valid. The value is considered valid
  // no invalid value was supplied during construction of this object or
  // if an invalid value was supplied and "m_current_value" is not equal
  // to "m_invalid_value".
  //
  // Returns true if "m_current_value" is valid, false otherwise.
  //----------------------------------------------------------------------
  bool is_valid() const {
    if (m_invalid_value_is_valid)
      return m_current_value != m_invalid_value;
    return true;
  }

  //----------------------------------------------------------------------
  // This function will call the cleanup callback provided in the
  // constructor one time if the value is considered valid (See is_valid()).
  // This function sets m_callback_called to true so we don't call the
  // cleanup callback multiple times on the same value.
  //----------------------------------------------------------------------
  void clean() {
    if (m_callback && !m_callback_called) {
      m_callback_called = true;
      if (is_valid())
        m_callback(m_current_value);
    }
  }

  //----------------------------------------------------------------------
  // Cancels the cleanup that would have been called on "m_current_value"
  // if it was valid. This function can be used to release the value
  // contained in this object so ownership can be transferred to the caller.
  //----------------------------------------------------------------------
  value_type release() {
    m_callback_called = true;
    return m_current_value;
  }

private:
  value_type m_current_value;
  const value_type m_invalid_value;
  CallbackType m_callback;
  bool m_callback_called;
  bool m_invalid_value_is_valid;

  // Outlaw default constructor, copy constructor and the assignment operator
  DISALLOW_COPY_AND_ASSIGN(CleanUp);
};

template <typename T, typename R, typename A0> class CleanUp2 {
public:
  typedef T value_type;
  typedef std::function<R(value_type, A0)> CallbackType;

  //----------------------------------------------------------------------
  // Constructor that sets the current value only. No values are
  // considered to be invalid and the cleanup function will be called
  // regardless of the value of m_current_value.
  //----------------------------------------------------------------------
  CleanUp2(value_type value, CallbackType callback, A0 arg)
      : m_current_value(value), m_invalid_value(), m_callback(callback),
        m_callback_called(false), m_invalid_value_is_valid(false),
        m_argument(arg) {}

  //----------------------------------------------------------------------
  // Constructor that sets the current value and also the invalid value.
  // The cleanup function will be called on "m_value" as long as it isn't
  // equal to "m_invalid_value".
  //----------------------------------------------------------------------
  CleanUp2(value_type value, value_type invalid, CallbackType callback, A0 arg)
      : m_current_value(value), m_invalid_value(invalid), m_callback(callback),
        m_callback_called(false), m_invalid_value_is_valid(true),
        m_argument(arg) {}

  //----------------------------------------------------------------------
  // Automatically cleanup when this object goes out of scope.
  //----------------------------------------------------------------------
  ~CleanUp2() { clean(); }

  //----------------------------------------------------------------------
  // Access the value stored in this class
  //----------------------------------------------------------------------
  value_type get() { return m_current_value; }

  //----------------------------------------------------------------------
  // Access the value stored in this class
  //----------------------------------------------------------------------
  const value_type get() const { return m_current_value; }

  //----------------------------------------------------------------------
  // Reset the owned value to "value". If a current value is valid and
  // the cleanup callback hasn't been called, the previous value will
  // be cleaned up (see void CleanUp::clean()).
  //----------------------------------------------------------------------
  void set(const value_type value) {
    // Cleanup the current value if needed
    clean();
    // Now set the new value and mark our callback as not called
    m_callback_called = false;
    m_current_value = value;
  }

  //----------------------------------------------------------------------
  // Checks is "m_current_value" is valid. The value is considered valid
  // no invalid value was supplied during construction of this object or
  // if an invalid value was supplied and "m_current_value" is not equal
  // to "m_invalid_value".
  //
  // Returns true if "m_current_value" is valid, false otherwise.
  //----------------------------------------------------------------------
  bool is_valid() const {
    if (m_invalid_value_is_valid)
      return m_current_value != m_invalid_value;
    return true;
  }

  //----------------------------------------------------------------------
  // This function will call the cleanup callback provided in the
  // constructor one time if the value is considered valid (See is_valid()).
  // This function sets m_callback_called to true so we don't call the
  // cleanup callback multiple times on the same value.
  //----------------------------------------------------------------------
  void clean() {
    if (m_callback && !m_callback_called) {
      m_callback_called = true;
      if (is_valid())
        m_callback(m_current_value, m_argument);
    }
  }

  //----------------------------------------------------------------------
  // Cancels the cleanup that would have been called on "m_current_value"
  // if it was valid. This function can be used to release the value
  // contained in this object so ownership can be transferred to the caller.
  //----------------------------------------------------------------------
  value_type release() {
    m_callback_called = true;
    return m_current_value;
  }

private:
  value_type m_current_value;
  const value_type m_invalid_value;
  CallbackType m_callback;
  bool m_callback_called;
  bool m_invalid_value_is_valid;
  A0 m_argument;

  // Outlaw default constructor, copy constructor and the assignment operator
  DISALLOW_COPY_AND_ASSIGN(CleanUp2);
};

} // namespace lldb_utility

#endif // #ifndef liblldb_CleanUp_h_