1//===-- CFCReleaser.h -------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_SOURCE_HOST_MACOSX_CFCPP_CFCRELEASER_H
10#define LLDB_SOURCE_HOST_MACOSX_CFCPP_CFCRELEASER_H
11
12#include <CoreFoundation/CoreFoundation.h>
13
14#ifdef __cplusplus
15
16#include <cassert>
17
18// Templatized CF helper class that can own any CF pointer and will
19// call CFRelease() on any valid pointer it owns unless that pointer is
20// explicitly released using the release() member function. This class
21// is designed to mimic the std::auto_ptr<T> class and has all of the
22// same functions. The one thing to watch out for is the
23// CFCReleaser<T>::release() function won't actually CFRelease any owned
24// pointer, it is designed to relinquish ownership of the pointer just
25// like std:auto_ptr<T>::release() does.
26template <class T> class CFCReleaser {
27public:
28  // Constructor that takes a pointer to a CF object that is
29  // to be released when this object goes out of scope
30  CFCReleaser(T ptr = NULL) : _ptr(ptr) {}
31
32  // Copy constructor
33  //
34  // Note that copying a CFCReleaser will not transfer
35  // ownership of the contained pointer, but it will bump its
36  // reference count. This is where this class differs from
37  // std::auto_ptr.
38  CFCReleaser(const CFCReleaser &rhs) : _ptr(rhs.get()) {
39    if (get())
40      ::CFRetain(get());
41  }
42
43  // The destructor will release the pointer that it contains
44  // if it has a valid pointer.
45  virtual ~CFCReleaser() { reset(); }
46
47  // Assignment operator.
48  //
49  // Note that assigning one CFCReleaser to another will
50  // not transfer ownership of the contained pointer, but it
51  // will bump its reference count. This is where this class
52  // differs from std::auto_ptr.
53  CFCReleaser &operator=(const CFCReleaser<T> &rhs) {
54    if (this != &rhs) {
55      // Replace our owned pointer with the new one
56      reset(rhs.get());
57      // Retain the current pointer that we own
58      if (get())
59        ::CFRetain(get());
60    }
61    return *this;
62  }
63
64  // Get the address of the contained type in case it needs
65  // to be passed to a function that will fill in a pointer
66  // value. The function currently will assert if _ptr is not
67  // NULL because the only time this method should be used is
68  // if another function will modify the contents, and we
69  // could leak a pointer if this is not NULL. If the
70  // assertion fires, check the offending code, or call
71  // reset() prior to using the "ptr_address()" member to make
72  // sure any owned objects has CFRelease called on it.
73  // I had to add the "enforce_null" bool here because some
74  // API's require the pointer address even though they don't change it.
75  T *ptr_address(bool enforce_null = true) {
76    if (enforce_null)
77      assert(_ptr == NULL);
78    return &_ptr;
79  }
80
81  // Access the pointer itself
82  T get() { return _ptr; }
83
84  const T get() const { return _ptr; }
85
86  // Set a new value for the pointer and CFRelease our old
87  // value if we had a valid one.
88  void reset(T ptr = NULL) {
89    if ((_ptr != NULL) && (ptr != _ptr))
90      ::CFRelease(_ptr);
91    _ptr = ptr;
92  }
93
94  // Release ownership without calling CFRelease. This class
95  // is designed to mimic std::auto_ptr<T>, so the release
96  // method releases ownership of the contained pointer
97  // and does NOT call CFRelease.
98  T release() {
99    T tmp = _ptr;
100    _ptr = NULL;
101    return tmp;
102  }
103
104private:
105  T _ptr;
106};
107
108#endif // #ifdef __cplusplus
109#endif // LLDB_SOURCE_HOST_MACOSX_CFCPP_CFCRELEASER_H
110