├── .gitignore
├── CMakeLists.txt
├── License.rst
├── Readme.rst
├── example
    └── python.hpp
├── include
    └── sg14
    │   └── memory.hpp
├── proposal
    ├── Makefile
    ├── docutils.conf
    ├── p0468.bs
    ├── pygments.css
    └── style.css
└── tests
    ├── doctest.cxx
    ├── doctest.hpp
    ├── python.cxx
    └── usage_example.cxx


/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | *.html
3 | 
4 | build/
5 | 


--------------------------------------------------------------------------------
/CMakeLists.txt:
--------------------------------------------------------------------------------
  1 | cmake_minimum_required(VERSION 3.8)
  2 | project(retain-ptr
  3 |   VERSION 0.1.0)
  4 | 
  5 | include(CMakeDependentOption)
  6 | include(CheckCXXCompilerFlag)
  7 | include(CTest)
  8 | 
  9 | find_package(PythonInterp 3.6)
 10 | find_package(PythonLibs 3.6)
 11 | 
 12 | set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 13 | set(CMAKE_CXX_STANDARD_REQUIRED ON)
 14 | 
 15 | set(TEST_SOURCE_DIR ${PROJECT_SOURCE_DIR}/tests)
 16 | set(TEST_BINARY_DIR ${PROJECT_BINARY_DIR}/tests)
 17 | 
 18 | set(USE_COVERAGE "--coverage")
 19 | set(WARN_MAYBE_UNINIT "-Wmaybe-unintialized")
 20 | set(WARN_EVERYTHING "-Weverything")
 21 | set(WARN_PEDANTIC "-Wpedantic")
 22 | set(WARN_ONE_LINE "-WL")
 23 | set(WARN_ERROR "-Werror")
 24 | set(WARN_EXTRA "-Wextra")
 25 | set(WARN_ODR "-Wodr")
 26 | set(WARN_ALL "-Wall")
 27 | 
 28 | set(WARN_NO_DOUBLE_PROMO "-Wno-double-promotion")
 29 | set(WARN_NO_UNUSED_FUNC "-Wno-unused-function")
 30 | set(WARN_NO_FLOAT_EQUAL "-Wno-float-equal")
 31 | set(WARN_NO_DEPRECATED "-Wno-deprecated-declarations")
 32 | set(WARN_NO_ATTRIBUTES "-Wno-attributes")
 33 | set(WARN_NO_SHADOW "-Wno-shadow")
 34 | set(WARN_NO_PADDED "-Wno-padded")
 35 | 
 36 | check_cxx_compiler_flag(${USE_COVERAGE} CAN_USE_COVERAGE)
 37 | 
 38 | check_cxx_compiler_flag(${WARN_MAYBE_UNINIT} CAN_WARN_MAYBE_UNINIT)
 39 | check_cxx_compiler_flag(${WARN_EVERYTHING} CAN_WARN_EVERYTHING)
 40 | check_cxx_compiler_flag(${WARN_PEDANTIC} CAN_WARN_PEDANTIC)
 41 | check_cxx_compiler_flag(${WARN_ONE_LINE} CAN_WARN_ONE_LINE)
 42 | check_cxx_compiler_flag(${WARN_ERROR} CAN_WARN_ERROR)
 43 | check_cxx_compiler_flag(${WARN_EXTRA} CAN_WARN_EXTRA)
 44 | check_cxx_compiler_flag(${WARN_ODR} CAN_WARN_ODR)
 45 | check_cxx_compiler_flag(${WARN_ALL} CAN_WARN_ALL)
 46 | 
 47 | check_cxx_compiler_flag(${WARN_NO_DOUBLE_PROMO} CAN_WARN_NO_DOUBLE_PROMO)
 48 | check_cxx_compiler_flag(${WARN_NO_UNUSED_FUNC} CAN_WARN_NO_UNUSED_FUNC)
 49 | check_cxx_compiler_flag(${WARN_NO_FLOAT_EQUAL} CAN_WARN_NO_FLOAT_EQUAL)
 50 | check_cxx_compiler_flag(${WARN_NO_DEPRECATED} CAN_WARN_NO_DEPRECATED)
 51 | check_cxx_compiler_flag(${WARN_NO_ATTRIBUTES} CAN_WARN_NO_ATTRIBUTES)
 52 | check_cxx_compiler_flag(${WARN_NO_SHADOW} CAN_WARN_NO_SHADOW)
 53 | check_cxx_compiler_flag(${WARN_NO_PADDED} CAN_WARN_NO_PADDED)
 54 | 
 55 | add_library(retain-ptr INTERFACE)
 56 | target_compile_features(retain-ptr INTERFACE cxx_std_17)
 57 | target_include_directories(retain-ptr INTERFACE
 58 |   ${PROJECT_SOURCE_DIR}/include)
 59 | 
 60 | if (PYTHONLIBS_FOUND)
 61 |   add_library(pywrap INTERFACE)
 62 |   target_include_directories(pywrap INTERFACE
 63 |     ${PROJECT_SOURCE_DIR}/example)
 64 |   target_include_directories(pywrap SYSTEM INTERFACE
 65 |     ${PYTHON_INCLUDE_DIR})
 66 |   target_link_libraries(pywrap INTERFACE ${PYTHON_LIBRARIES})
 67 |   if (MINGW)
 68 |     target_compile_definitions(pywrap INTERFACE "-D_hypot=hypot")
 69 |   endif()
 70 | endif ()
 71 | 
 72 | add_library(doctest-main STATIC ${TEST_SOURCE_DIR}/doctest.cxx)
 73 | target_compile_options(doctest-main
 74 |   PUBLIC
 75 |     $<$<BOOL:${CAN_USE_COVERAGE}>:${USE_COVERAGE}>
 76 |     $<$<BOOL:${CAN_WARN_MAYBE_UNINIT}>:${WARN_MAYBE_UNINIT}>
 77 |     $<$<BOOL:${CAN_WARN_EVERYTHING}>:${WARN_EVERYTHING}>
 78 |     $<$<BOOL:${CAN_WARN_PEDANTIC}>:${WARN_PEDANTIC}>
 79 |     $<$<BOOL:${CAN_WARN_EXTRA}>:${WARN_EXTRA}>
 80 |     $<$<BOOL:${CAN_WARN_ODR}>:${WARN_ODR}>
 81 |     $<$<BOOL:${CAN_WARN_ALL}>:${WARN_ALL}>
 82 | 
 83 |     $<$<BOOL:${CAN_WARN_NO_DOUBLE_PROMO}>:${WARN_NO_DOUBLE_PROMO}>
 84 |     $<$<BOOL:${CAN_WARN_NO_UNUSED_FUNC}>:${WARN_NO_UNUSED_FUNC}>
 85 |     $<$<BOOL:${CAN_WARN_NO_FLOAT_EQUAL}>:${WARN_NO_FLOAT_EQUAL}>
 86 |     $<$<BOOL:${CAN_WARN_NO_DEPRECATED}>:${WARN_NO_DEPRECATED}>
 87 |     $<$<BOOL:${CAN_WARN_NO_ATTRIBUTES}>:${WARN_NO_ATTRIBUTES}>
 88 |     $<$<BOOL:${CAN_WARN_NO_SHADOW}>:${WARN_NO_SHADOW}>
 89 |     $<$<BOOL:${CAN_WARN_NO_PADDED}>:${WARN_NO_PADDED}>
 90 | 
 91 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-potentially-evaluated-expression>
 92 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-unneeded-internal-declaration>
 93 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-disabled-macro-expansion>
 94 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-unused-member-function>
 95 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-c++98-compat-pedantic>
 96 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-exit-time-destructors>
 97 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-c++98-compat>
 98 |     $<$<CXX_COMPILER_ID:Clang>:-Wno-weak-vtables>)
 99 | 
100 | if (TARGET pywrap)
101 |   add_executable(test-python ${TEST_SOURCE_DIR}/python.cxx)
102 |   add_test(python test-python)
103 |   target_include_directories(test-python SYSTEM PRIVATE ${TEST_SOURCE_DIR})
104 |   target_link_libraries(test-python PUBLIC retain-ptr pywrap doctest-main)
105 |   target_link_libraries(test-python PRIVATE
106 |     $<$<BOOL:${CAN_USE_COVERAGE}>:${USE_COVERAGE}>)
107 | endif ()
108 | 
109 | add_executable(test-usage_example ${TEST_SOURCE_DIR}/usage_example.cxx)
110 | add_test(usage_example test-usage_example)
111 | target_link_libraries(test-usage_example PUBLIC retain-ptr doctest-main)
112 | target_link_libraries(test-usage_example PRIVATE
113 |   $<$<BOOL:${CAN_USE_COVERAGE}>:${USE_COVERAGE}>)
114 | 


--------------------------------------------------------------------------------
/License.rst:
--------------------------------------------------------------------------------
 1 | .. |copy| unicode:: U+000A9
 2 | 
 3 | Copyright |copy| 2016, Isabella Muerte
 4 | All rights reserved.
 5 | 
 6 | Redistribution and use in source and binary forms, with or without
 7 | modification, are permitted provided that the following conditions are met:
 8 | 
 9 |   1. Redistributions of source code must retain the above copyright notice,
10 |      this list of conditions and the following disclaimer.
11 | 
12 |   2. Redistributions in binary form must reproduce the above copyright notice,
13 |      this list of conditions and the following disclaimer in the documentation
14 |      and/or other materials provided with the distribution.
15 | 
16 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
20 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 | 


--------------------------------------------------------------------------------
/Readme.rst:
--------------------------------------------------------------------------------
 1 | Overview
 2 | ========
 3 | 
 4 | This is a proposal (P0468_) and reference implementation for an intrusive smart
 5 | pointer for the C++ standard library. The example provided is fragile, as it is
 6 | only being written against Python 3.5. More examples will eventually follow.
 7 | 
 8 | The implementation provided works with C++14, but could be backported to C++11.
 9 | Due to the feature lockin of C++17, this will most likely not make it into the
10 | standard until C++20.
11 | 
12 | Creating the HTML file for the proposal requires ``rst2html.py``, which is a
13 | part of the python ``docutils`` package.
14 | 
15 | The reference implementation (everything under the include directory) is under
16 | the BSD 2-clause.
17 | 
18 | .. _P0468: https://wg21.link/p0468
19 | 


--------------------------------------------------------------------------------
/example/python.hpp:
--------------------------------------------------------------------------------
  1 | #ifndef PYTHON_WRAPPER_EXAMPLE_HPP
  2 | #define PYTHON_WRAPPER_EXAMPLE_HPP
  3 | 
  4 | #include <stdexcept>
  5 | 
  6 | #include <sg14/memory.hpp>
  7 | #include <Python.h>
  8 | 
  9 | namespace py {
 10 | 
 11 | struct snake_traits final {
 12 |   static void increment (PyObject* obj) noexcept { Py_INCREF(obj); }
 13 |   static void decrement (PyObject* obj) noexcept { Py_DECREF(obj); }
 14 | };
 15 | 
 16 | using object = sg14::retain_ptr<PyObject, snake_traits>;
 17 | 
 18 | struct tuple {
 19 |   using index_type = Py_ssize_t;
 20 | 
 21 |   tuple (object obj) noexcept(false) : obj { obj } {
 22 |     if (not PyTuple_Check(obj.get())) {
 23 |       throw std::logic_error("Was not passed a tuple");
 24 |     }
 25 |   }
 26 | 
 27 |   tuple (object::pointer obj) : tuple(object(obj)) { }
 28 |   tuple (index_type n) :
 29 |     tuple(PyTuple_New(n))
 30 |   { }
 31 | 
 32 |   object operator [] (index_type idx) const noexcept {
 33 |     return { PyTuple_GetItem(this->obj.get(), idx), sg14::retain_object };
 34 |   }
 35 | 
 36 |   index_type size () const noexcept { return PyTuple_Size(this->obj.get()); }
 37 | 
 38 |   tuple slice (index_type low, index_type high) const noexcept {
 39 |     return PyTuple_GetSlice(this->obj.get(), low, high);
 40 |   }
 41 | 
 42 |   auto get () const noexcept { return this->obj.get(); }
 43 | 
 44 | private:
 45 |   object obj;
 46 | };
 47 | 
 48 | struct list {
 49 |   using index_type = Py_ssize_t;
 50 | 
 51 |   list (object obj) noexcept(false) : obj { obj } {
 52 |     if (not PyList_Check(obj.get())) {
 53 |       throw std::logic_error("Was not passed a list");
 54 |     }
 55 |   }
 56 |   list (object::pointer obj) : list(object(obj)) { }
 57 |   list (index_type n) :
 58 |     list(PyList_New(n))
 59 |   { }
 60 | 
 61 |   object operator [] (index_type idx) const noexcept {
 62 |     return { PyList_GetItem(this->obj.get(), idx), sg14::retain_object };
 63 |   }
 64 | 
 65 |   void insert (index_type idx, object item) noexcept {
 66 |     PyList_Insert(this->obj.get(), idx, item.get());
 67 |   }
 68 | 
 69 |   void append (object item) noexcept {
 70 |     PyList_Append(this->obj.get(), item.get());
 71 |   }
 72 | 
 73 |   index_type size () const noexcept {
 74 |     return PyList_Size(this->obj.get());
 75 |   }
 76 | 
 77 |   void slice (index_type low, index_type high, list items) noexcept {
 78 |     PyList_SetSlice(this->obj.get(), low, high, items.obj.get());
 79 |   }
 80 | 
 81 |   list slice (index_type low, index_type high) const noexcept {
 82 |     return PyList_GetSlice(this->obj.get(), low, high);
 83 |   }
 84 | 
 85 |   void reverse () noexcept { PyList_Reverse(this->obj.get()); }
 86 |   void sort () noexcept { PyList_Sort(this->obj.get()); }
 87 | 
 88 |   auto get () const noexcept { return this->obj.get(); }
 89 | 
 90 | private:
 91 |   object obj;
 92 | };
 93 | 
 94 | inline tuple as_tuple (list const& in) { return PySequence_Tuple(in.get()); }
 95 | inline list as_list (tuple const& in) { return PyList_AsTuple(in.get()); }
 96 | 
 97 | } /* namespace py */
 98 | 
 99 | #endif /* PYTHON_WRAPPER_EXAMPLE_HPP */
100 | 


--------------------------------------------------------------------------------
/include/sg14/memory.hpp:
--------------------------------------------------------------------------------
  1 | #ifndef SG14_MEMORY_HPP
  2 | #define SG14_MEMORY_HPP
  3 | 
  4 | #include <type_traits>
  5 | #include <functional>
  6 | #include <utility>
  7 | #include <memory>
  8 | #include <atomic>
  9 | 
 10 | namespace sg14 {
 11 | 
 12 | using std::is_convertible;
 13 | using std::is_same;
 14 | 
 15 | using std::conditional_t;
 16 | using std::add_pointer_t;
 17 | using std::nullptr_t;
 18 | 
 19 | using std::declval;
 20 | 
 21 | } /* namespace sg14 */
 22 | 
 23 | namespace sg14 {
 24 | namespace impl {
 25 | 
 26 | template <class T> struct identity { using type = T; };
 27 | 
 28 | template <class T, class Void, template <class...> class, class...>
 29 | struct detector : identity<T> { using value_t = std::false_type; };
 30 | 
 31 | template <class T, template <class...> class U, class... Args>
 32 | struct detector<T, std::void_t<U<Args...>>, U, Args...> :
 33 |   identity<U<Args...>>
 34 | { using value_t = std::true_type; };
 35 | 
 36 | struct nonesuch final {
 37 |   nonesuch (nonesuch const&) = delete;
 38 |   nonesuch () = delete;
 39 |   ~nonesuch () = delete;
 40 | 
 41 |   void operator = (nonesuch const&) = delete;
 42 | };
 43 | 
 44 | template <class T, template <class...> class U, class... Args>
 45 | using detected_or = detector<T, void, U, Args...>;
 46 | 
 47 | template <template <class...> class T, class... Args>
 48 | using detected_t = typename detected_or<nonesuch, T, Args...>::type;
 49 | 
 50 | template <class T, template <class...> class U, class... Args>
 51 | using detected_or_t = typename detected_or<T, U, Args...>::type;
 52 | 
 53 | template <template <class...> class T, class... Args>
 54 | using is_detected = typename detected_or<nonesuch, T, Args...>::value_t;
 55 | 
 56 | template <class To, template <class...> class T, class... Args>
 57 | using is_detected_convertible = std::is_convertible<
 58 |   detected_t<T, Args...>,
 59 |   To
 60 | >;
 61 | 
 62 | template <class T, template <class...> class U, class... Args>
 63 | using is_detected_exact = std::is_same<T, detected_t<U, Args...>>;
 64 | 
 65 | template <class T>
 66 | using has_pointer = typename T::pointer;
 67 | 
 68 | template <class T>
 69 | using has_default_action = typename T::default_action;
 70 | 
 71 | template <class T, class P>
 72 | using has_use_count = decltype(T::use_count(std::declval<P>()));
 73 | 
 74 | }} /* namespace sg14::impl */
 75 | 
 76 | namespace sg14 {
 77 | 
 78 | using impl::detected_or_t;
 79 | using impl::is_detected;
 80 | 
 81 | template <class> struct retain_traits;
 82 | 
 83 | template <class T>
 84 | struct atomic_reference_count {
 85 |   template <class> friend class retain_traits;
 86 | protected:
 87 |   atomic_reference_count () = default;
 88 | private:
 89 |   std::atomic<long> count { 1 };
 90 | };
 91 | 
 92 | template <class T>
 93 | struct reference_count {
 94 |   template <class> friend class retain_traits;
 95 | protected:
 96 |   reference_count () = default;
 97 | private:
 98 |   long count { 1 };
 99 | };
100 | 
101 | struct retain_object_t {  retain_object_t () noexcept = default; };
102 | struct adopt_object_t {  adopt_object_t () noexcept = default; };
103 | 
104 | constexpr retain_object_t retain_object { };
105 | constexpr adopt_object_t adopt_object { };
106 | 
107 | template <class T>
108 | struct retain_traits final {
109 |   template <class U>
110 |   using enable_if_base = std::enable_if_t<std::is_base_of_v<U, T>>;
111 | 
112 |   template <class U, class = enable_if_base<U>>
113 |   static void increment (atomic_reference_count<U>* ptr) noexcept {
114 |     ptr->count.fetch_add(1, std::memory_order_relaxed);
115 |   }
116 | 
117 |   template <class U, class = enable_if_base<U>>
118 |   static void decrement (atomic_reference_count<U>* ptr) noexcept {
119 |     ptr->count.fetch_sub(1, std::memory_order_acq_rel);
120 |     if (not use_count(ptr)) { delete static_cast<T*>(ptr); }
121 |   }
122 | 
123 |   template <class U, class = enable_if_base<U>>
124 |   static long use_count (atomic_reference_count<U>* ptr) noexcept {
125 |     return ptr->count.load(std::memory_order_relaxed);
126 |   }
127 | 
128 |   template <class U, class = enable_if_base<U>>
129 |   static void increment (reference_count<U>* ptr) noexcept {
130 |     ++ptr->count;
131 |   }
132 |   template <class U, class = enable_if_base<U>>
133 |   static void decrement (reference_count<U>* ptr) noexcept {
134 |     --ptr->count;
135 |     if (not use_count(ptr)) { delete static_cast<T*>(ptr); }
136 |   }
137 |   template <class U, class = enable_if_base<U>>
138 |   static long use_count (reference_count<U>* ptr) noexcept {
139 |     return ptr->count;
140 |   }
141 | };
142 | 
143 | template <class T, class R=retain_traits<T>>
144 | struct retain_ptr {
145 |   using element_type = T;
146 |   using traits_type = R;
147 | 
148 |   using pointer = detected_or_t<
149 |     add_pointer_t<element_type>,
150 |     impl::has_pointer,
151 |     traits_type
152 |   >;
153 | 
154 |   using default_action = detected_or_t<
155 |     adopt_object_t,
156 |     impl::has_default_action,
157 |     traits_type
158 |   >;
159 | 
160 |   static constexpr bool CheckAction = std::disjunction_v<
161 |     std::is_same<default_action, adopt_object_t>,
162 |     std::is_same<default_action, retain_object_t>
163 |   >;
164 | 
165 |   static_assert(
166 |     CheckAction,
167 |     "traits_type::default_action must be adopt_object_t or retain_object_t");
168 | 
169 |   static constexpr auto has_use_count = is_detected<
170 |     impl::has_use_count,
171 |     traits_type,
172 |     pointer
173 |   > { };
174 | 
175 |   retain_ptr (pointer ptr, retain_object_t) :
176 |     retain_ptr { ptr, adopt_object }
177 |   { if (*this) { traits_type::increment(this->get()); } }
178 | 
179 |   retain_ptr (pointer ptr, adopt_object_t) : ptr { ptr } { }
180 | 
181 |   explicit retain_ptr (pointer ptr) :
182 |     retain_ptr { ptr, default_action() }
183 |   { }
184 | 
185 |   retain_ptr (nullptr_t) : retain_ptr { } { }
186 | 
187 |   retain_ptr (retain_ptr const& that) :
188 |     ptr { that.ptr }
189 |   { if (*this) { traits_type::increment(this->get()); } }
190 | 
191 |   retain_ptr (retain_ptr&& that) noexcept :
192 |     ptr { that.detach() }
193 |   { }
194 | 
195 |   retain_ptr () noexcept = default;
196 |   ~retain_ptr () {
197 |     if (*this) { traits_type::decrement(this->get()); }
198 |   }
199 | 
200 |   retain_ptr& operator = (retain_ptr const& that) {
201 |     retain_ptr(that).swap(*this);
202 |     return *this;
203 |   }
204 | 
205 |   retain_ptr& operator = (retain_ptr&& that) {
206 |     retain_ptr(std::move(that)).swap(*this);
207 |     return *this;
208 |   }
209 | 
210 |   retain_ptr& operator = (nullptr_t) noexcept { this->reset(); return *this; }
211 | 
212 |   void swap (retain_ptr& that) noexcept {
213 |     using std::swap;
214 |     swap(this->ptr, that.ptr);
215 |   }
216 | 
217 |   explicit operator bool () const noexcept { return this->get(); }
218 |   decltype(auto) operator * () const noexcept { return *this->get(); }
219 |   pointer operator -> () const noexcept { return this->get(); }
220 | 
221 |   pointer get () const noexcept { return this->ptr; }
222 | 
223 |   long use_count () const {
224 |     if constexpr (has_use_count) {
225 |       return this->get() ? traits_type::use_count(this->get()) : 0;
226 |     } else { return -1; }
227 |   }
228 | 
229 |   pointer detach () noexcept {
230 |     auto ptr = this->get();
231 |     this->ptr = pointer { };
232 |     return ptr;
233 |   }
234 | 
235 |   void reset (pointer ptr, retain_object_t) {
236 |     *this = retain_ptr(ptr, retain_object);
237 |   }
238 | 
239 |   void reset (pointer ptr, adopt_object_t) noexcept {
240 |     *this = retain_ptr(ptr, adopt_object);
241 |   }
242 | 
243 |   void reset (pointer ptr) { *this = retain_ptr(ptr, default_action()); }
244 | 
245 | private:
246 |   pointer ptr { };
247 | };
248 | 
249 | template <class T, class R>
250 | void swap (retain_ptr<T, R>& lhs, retain_ptr<T, R>& rhs) noexcept {
251 |   lhs.swap(rhs);
252 | }
253 | 
254 | template <class T, class R>
255 | bool operator == (
256 |   retain_ptr<T, R> const& lhs,
257 |   retain_ptr<T, R> const& rhs
258 | ) noexcept { return lhs.get() == rhs.get(); }
259 | 
260 | template <class T, class R>
261 | bool operator != (
262 |   retain_ptr<T, R> const& lhs,
263 |   retain_ptr<T, R> const& rhs
264 | ) noexcept { return lhs.get() != rhs.get(); }
265 | 
266 | template <class T, class R>
267 | bool operator >= (
268 |   retain_ptr<T, R> const& lhs,
269 |   retain_ptr<T, R> const& rhs
270 | ) noexcept { return lhs.get() >= rhs.get(); }
271 | 
272 | template <class T, class R>
273 | bool operator <= (
274 |   retain_ptr<T, R> const& lhs,
275 |   retain_ptr<T, R> const& rhs
276 | ) noexcept { return lhs.get() <= rhs.get(); }
277 | 
278 | template <class T, class R>
279 | bool operator > (
280 |   retain_ptr<T, R> const& lhs,
281 |   retain_ptr<T, R> const& rhs
282 | ) noexcept { return lhs.get() > rhs.get(); }
283 | 
284 | template <class T, class R>
285 | bool operator < (
286 |   retain_ptr<T, R> const& lhs,
287 |   retain_ptr<T, R> const& rhs
288 | ) noexcept { return lhs.get() < rhs.get(); }
289 | 
290 | template <class T, class R>
291 | bool operator == (retain_ptr<T, R> const& lhs, nullptr_t) noexcept {
292 |   return bool(lhs);
293 | }
294 | 
295 | template <class T, class R>
296 | bool operator != (retain_ptr<T, R> const& lhs, nullptr_t) noexcept {
297 |   return not lhs;
298 | }
299 | 
300 | template <class T, class R>
301 | bool operator >= (retain_ptr<T, R> const& lhs, nullptr_t) noexcept {
302 |   return not (lhs < nullptr);
303 | }
304 | 
305 | template <class T, class R>
306 | bool operator <= (retain_ptr<T, R> const& lhs, nullptr_t) noexcept {
307 |   return nullptr < lhs;
308 | }
309 | 
310 | template <class T, class R>
311 | bool operator > (retain_ptr<T, R> const& lhs, nullptr_t) noexcept {
312 |   return not (nullptr < lhs);
313 | }
314 | 
315 | template <class T, class R>
316 | bool operator < (retain_ptr<T, R> const& lhs, nullptr_t) noexcept {
317 |   return std::less<>()(lhs.get(), nullptr);
318 | }
319 | 
320 | template <class T, class R>
321 | bool operator == (nullptr_t, retain_ptr<T, R> const& rhs) noexcept {
322 |   return not rhs;
323 | }
324 | 
325 | template <class T, class R>
326 | bool operator != (nullptr_t, retain_ptr<T, R> const& rhs) noexcept {
327 |   return bool(rhs);
328 | }
329 | 
330 | template <class T, class R>
331 | bool operator >= (nullptr_t, retain_ptr<T, R> const& rhs) noexcept {
332 |   return not (nullptr < rhs);
333 | }
334 | 
335 | template <class T, class R>
336 | bool operator <= (nullptr_t, retain_ptr<T, R> const& rhs) noexcept;
337 | 
338 | template <class T, class R>
339 | bool operator > (nullptr_t, retain_ptr<T, R> const& rhs) noexcept {
340 |   return not (rhs < nullptr);
341 | }
342 | 
343 | template <class T, class R>
344 | bool operator < (nullptr_t, retain_ptr<T, R> const& rhs) noexcept {
345 |   return std::less<>()(rhs.get(), nullptr);
346 | }
347 | 
348 | } /* namespace sg14 */
349 | 
350 | #endif /* SG14_MEMORY_HPP */
351 | 


--------------------------------------------------------------------------------
/proposal/Makefile:
--------------------------------------------------------------------------------
 1 | %.html : %.rst
 2 | 	@rst2html.py --stylesheet=style.css,pygments.css $< $@
 3 | 
 4 | p0468.html: p0468.rst style.css pygments.css
 5 | 
 6 | all: p0468.html
 7 | 
 8 | clean:
 9 | 	@rm *.html
10 | 


--------------------------------------------------------------------------------
/proposal/docutils.conf:
--------------------------------------------------------------------------------
1 | [parsers]
2 | [restructuredtext parser]
3 | syntax_highlight=short
4 | 


--------------------------------------------------------------------------------
/proposal/p0468.bs:
--------------------------------------------------------------------------------
  1 | <pre class='metadata'>
  2 | Title: An Intrusive Smart Pointer
  3 | Shortname: P0468
  4 | Revision: 1
  5 | Audience: LEWG
  6 | Audience: LWG
  7 | Status: P
  8 | Group: WG21
  9 | URL: https://wg21.link/p0468r1
 10 | Editor: Isabella Muerte, https://twitter.com/slurpsmadrips
 11 | Date: 2018-06-19
 12 | Markup Shorthands: markdown yes
 13 | Abstract: A smart pointer is needed to manage objects with internal reference
 14 | Abstract: counts to reduce maintenance overhead of C and C++ APIs.
 15 | </pre>
 16 | 
 17 | # Acknowledgements # {#acknowledgements}
 18 | 
 19 | I'd like to thank the following:
 20 | 
 21 |  * Jackie Kay and Brittany Friedman for encouraging me to submit this proposal.
 22 |  * Gor Nishanov, whose coroutine slides at CppCon 2016 gave me the final push
 23 |     to sit down and write this.
 24 |  * Bryce "Wash" Lelbach for representing this paper when I was unable to.
 25 |  * Mark Zeren for *constantly* bugging me to see if I might update this paper.
 26 |  * JF Bastien and Billy O'Neal for assisting me with some atomic operations,
 27 |     which I am absolute garbage at.
 28 | 
 29 | # Revision History # {#changelog}
 30 | 
 31 | ## Revision 1 ## {#r1}
 32 | 
 33 |  * Rewrote proposal in bikeshed, the hot new format that every cool proposal
 34 |     writer is using now.
 35 |  * Clarified section on addressof operator, now that `c_ptr` is being
 36 |     submitted
 37 |  * Removed `retain_ptr::unique` as it was removed from `shared_ptr` for C++20.
 38 |  * Changed name of `retain_t` to `retain_object_t`
 39 |  * Changed atomicity of `atomic_reference_count` based on suggestions from
 40 |     Billy O'Neal.
 41 |  * Changed wording to use C++17/C++20 features.
 42 |  * Changed order of document. [[#specification]] is now at the very end
 43 |     of the document, and [[#examples]] are further up.
 44 |  * Added `adopt_object_t` and `default_action` to let users decide what
 45 |     action they want on construction and reset.
 46 |  * Added `static_pointer_cast`, `dynamic_pointer_cast`, `const_pointer_cast`,
 47 |     and `reinterpret_pointer_cast`.
 48 |  * Added deduction guides to bring `retain_ptr` in line with other smart
 49 |     pointers
 50 | 
 51 | ## Revision 0 ## {#r0}
 52 | 
 53 |   Initial Release
 54 | 
 55 | # Motivation # {#motivation}
 56 | 
 57 | There are a wide variety of C and C++ APIs that rely on reference counting,
 58 | but either because of the language (C) or the age of the library (C++), they
 59 | are unable to be safely use with either `std::unique_ptr<T>` or
 60 | `std::shared_ptr<T>`. In the former case, there is no guaranteed way to make
 61 | sure the `unique_ptr` is the last instance (i.e., that it is *unique*), and in
 62 | the latter case, `shared_ptr` manages its own API. In addition, existing
 63 | intrusive smart pointers such as <a href="https://bit.ly/intrusive-ptr">
 64 | `boost::intrusive_ptr<T>`</a>, <a href="https://bit.ly/com-ptr">Microsoft's
 65 | `ComPtr<T>`</a>, or <a href="https://git.io/fCl9x">WebKit's aptly named
 66 | `WTF::RefPtr<T>`</a> do not meet the needs of modern C++ smart pointers or APIs.
 67 | This proposal attempts to solve these shortcomings in an extensible and future
 68 | proof manner, while permitting a simple upgrade path for existing project
 69 | specific intrusive smart pointers and providing the opportunity for value
 70 | semantics when interfacing with opaque interfaces.
 71 | 
 72 | Those that work on systems or tools that rely on reference counting stand to
 73 | benefit most from `retain_ptr`. Additionally, `retain_ptr` would be a benefit
 74 | to standard library implementers for types that *secretly* use intrusive
 75 | reference counting such as a coroutines capable future and promise.
 76 | 
 77 | If `retain_ptr` is added to the standard library, the C++ community would also
 78 | be one step closer to a non-atomic `shared_ptr` and `weak_ptr`, much like
 79 | Rust's `Rc<T>`.
 80 | 
 81 | A reference implementation of `retain_ptr`, along with examples of its use,
 82 | can be found on [[implementation|github]].
 83 | 
 84 | # Scope and Impact # {#scope}
 85 | 
 86 | `retain_ptr<T, R>` would ideally be available in the `<memory>` standard
 87 | header. It is a pure extension to the C++ standard library and can (more or
 88 | less) be implemented using any conforming C++14 or C++11 compiler with very
 89 | little effort. See the [[#specification]] for interface and behavior
 90 | details.
 91 | 
 92 | # Frequently Asked Questions # {#faq}
 93 | 
 94 | Several common questions regarding the design of `retain_ptr<T, R>` can be
 95 | found below.
 96 | 
 97 | ## How does `intrusive_ptr` not meet the needs of modern C++? ## {#faq-1}
 98 | 
 99 | `boost::intrusive_ptr` has had nearly the same interface since its introduction
100 | in 2001 by Peter Dimov. Furthermore, `boost::intrusive_ptr` has several
101 | failings in its API that cannot be changed from without breaking compatibility.
102 | When constructing a `boost::intrusive_ptr`, by default it increments the
103 | reference count. This is because of its `intrusive_ref_count` mixin, which
104 | starts with a reference count of 0 when it is default constructed. Out of all
105 | the libraries I tried to look at, this was the one instance where an object
106 | required it be incremented after construction. This proposal rectifies this
107 | by permitting each traits instance to choose its default action during
108 | construction.
109 | 
110 | Additionally, `boost::intrusive_ptr` does not have the ability to "overload"
111 | its `pointer` type member, requiring some additional work when interfacing with
112 | C APIs (e.g., `boost::intrusive_ptr<decltype(*declval<cl_mem>())>`). This
113 | also precludes it from working with types that meet the *NullablePointer* 
114 | named requirements (a feature that `unique_ptr` supports).
115 | 
116 | Furthermore, `boost::intrusive_ptr` relies on ADL calls of two functions:
117 | 
118 |  * `intrusive_add_ref`
119 |  * `intrusive_release`
120 | 
121 | While this approach is fine in most cases, it does remove the ability to easily
122 | "swap out" the actions taken when increment or decrementing the reference count
123 | (e.g., setting a debugger breakpoint on a specific traits implementation, but
124 | not on *all* traits implementations). This naming convention uses terms found
125 | in Microsoft's COM. While this isn't an issue per se, it would be odd to have
126 | functions with those names found in the standard.
127 | 
128 | ## Why is it called `retain_ptr` and not `intrusive_ptr`? ## {#faq-2}
129 | 
130 | `retain_ptr` diverges from the design of `boost::intrusive_ptr`. It was decided
131 | to change the name so as to not cause assumptions of `retain_ptr`'s interface
132 | and behavior.
133 | 
134 | Some additional names that might be considered (for bikeshedding) are:
135 | 
136 |  * `extend_ptr`
137 |  * `counted_ptr`
138 |  * `borrow_ptr`
139 |  * `mutual_ptr`
140 |  * `joint_ptr`
141 | 
142 | Comedy Option:
143 | 
144 |  * `auto_ptr`
145 | 
146 | ## Is `retain_ptr` atomic? ## {#faq-3}
147 | 
148 | `retain_ptr` is only atomic in its reference count increment and decrements
149 | if the object it manages is itself atomic in its reference count operations.
150 | 
151 | ## Does `retain_ptr` support allocators? ## {#faq-4}
152 | 
153 | `retain_ptr` itself does not support allocators, however the object whose
154 | lifetime it extends can.
155 | 
156 | 
157 | ## Can `retain_ptr` be constexpr? ## {#faq-5}
158 | 
159 | Possibly. However, I question the usefulness for a constexpr capable intrusive
160 | smart pointer, as most use cases are intended for non-constexpr capable
161 | interfaces such as incomplete types and polymorphic classes. Additionally,
162 | `retain_ptr` allows one to utilize value semantics on C and C++ APIs. If this
163 | is desired in a constexpr context, one can simply use constexpr values (i.e.,
164 | reference counting is not a necessary aspect of constexpr)
165 | 
166 | ## Why does `retain_ptr` use `detach`? ## {#faq-6}
167 | 
168 | `retain_ptr` diverges from common smart pointer functions that release
169 | ownership of their managed object via a member function named `release()`.
170 | This `release()` function is intended to return the managed object in its
171 | current state, and place the smart pointer into an *empty* state. `retain_ptr`
172 | opts to use the name `detach` for semantic reasons. Many objects that might be
173 | managed by `retain_ptr` tend to use a function or operation named `release` to
174 | decrement the internal reference count. To reduce confusion for implementers,
175 | and those curious enough to look under the hood, a different name was chosen.
176 | This name (i.e., `detach()` was also used by `boost::intrusive_ptr`.
177 | 
178 | A `retain_ptr` does not *own* the object it manages, rather it is *extending*
179 | ownership. When we use `detach`, we aren't telling the `retain_ptr` to release
180 | ownership to the caller. Instead we are expressing our desire for the
181 | `retain_ptr` to *detach* its management of the stored object.
182 | 
183 | That said, this isn't a line in the sand and `release` will be used if the
184 | committee chooses to. Some other possible names for `detach()` that could be
185 | considered are `withdraw`, `discard`, and `disengage`.
186 | 
187 | ## Does `retain_ptr` adopt or retain an object on construction? ## {#faq-7}
188 | 
189 | The default action that `retain_ptr` takes on construction or reset is
190 | determined by the `traits_type` for the `retain_ptr`. If the traits type
191 | has a member named `default_action`, the `retain_ptr` will use that to delegate
192 | to the correct constructor. If there is no type alias member named
193 | `default_action`, the default operation is to *adopt* the object (i.e., it
194 | does not increment the reference count during its construction). The
195 | `default_action` type alias *must* be either `adopt_object_t` or
196 | `retain_object_t`.
197 | 
198 | ## Why provide `retain_object_t` and `adopt_object_t`? ## {#faq-8}
199 | 
200 | `retain_object_t` and `adopt_object_t` act as sentinel types to provide
201 | explicit requests to either *extend* or *adopt* an object when constructing
202 | or resetting a `retain_ptr`. This mostly comes into play when interacting
203 | with APIs that return a borrowed (rather than a new) reference to an object
204 | without increment its reference count.
205 | 
206 | Technically, an `enum class retain : bool { no, yes }` would be possible.
207 | However, this would be the first time such an API is placed into the standard
208 | library. Using a boolean parameter, as found in `boost::intrusive_ptr` is
209 | unsatisfactory and does not help describe the operation the user is requesting.
210 | 
211 | The names of these sentinels are available for bikeshedding. Some other
212 | possible names for `retain_object_t` include:
213 | 
214 |  * `retain_element_t`
215 |  * `extend_element_t`
216 |  * `retainobj_t`
217 |  * `extendobj_t`
218 | 
219 | While `adopt_object_t` names include:
220 | 
221 |  * `borrow_object_t`
222 |  * `borrow_element_t`
223 |  * `borrowobj_t`
224 |  * `adopt_element_t`
225 |  * `adoptobj_t`
226 | 
227 | ## Does `retain_ptr` overload the addressof operator? ## {#faq-9}
228 | 
229 | Originally, this proposal suggested `retain_ptr` might in some small edge case
230 | require an overload for the addressof `operator &`. This was, with absolutely
231 | no surprise, contentious and asked to be removed. However, Microsoft's
232 | `ComPtr<T>` overloads the addressof operator for initializing it via C APIs
233 | (i.e., APIs which initialize a pointer to a pointer). Since then, JeanHyde
234 | Meneide's *c_ptr* proposal was written and thus solves this slight issue.
235 | 
236 | ## Can `retain_traits` store state? ## {#faq-10}
237 | 
238 | No. Any important state regarding the object or how it is retained, can be
239 | stored in the object itself. For example, if the reference count needs to be
240 | external from the object, `std::shared_ptr` would be a better choice.
241 | 
242 | ## Why not just wrap a `unique_ptr` with a custom deleter? ## {#faq-11}
243 | 
244 | This is an extraordinary amount of code across many existing libraries that
245 | would not be guaranteed to have a homogenous interface. For example, using
246 | `retain_ptr` with an OpenCL context object (without checking for errors in both
247 | implementations) is as simple as:
248 | 
249 | ```cpp
250 | struct context_traits {
251 |   using pointer = cl_context;
252 |   static void increment (pointer p) { clRetainContext(p); }
253 |   static void decrement (pointer p) { clReleaseContext(p); }
254 | };
255 | 
256 | struct context {
257 |   using handle_type = retain_ptr<cl_context, context_traits>;
258 |   using pointer = handle_type::pointer;
259 |   context (pointer p, retain_object_t) : handle(p, retain) { }
260 |   context (pointer p) : handle(p) { }
261 | private:
262 |   handle_type handle;
263 | };
264 | 
265 | ```
266 | 
267 | Using the `unique_ptr` approach requires more effort. In this case, it is
268 | twice as long to get the same functionality.
269 | 
270 | ```cpp
271 | struct context_deleter {
272 |   using pointer = cl_context;
273 |   void increment (pointer p) const {
274 |     if (p) { clRetainContext(p); } // retain_ptr checks for null for us
275 |   }
276 |   void operator () (pointer p) const { clReleaseContext(p); }
277 | };
278 | 
279 | struct retain_object_t { };
280 | constexpr retain_object_t retain { };
281 | 
282 | struct context {
283 |   using handle_type = unique_ptr<cl_context, context_deleter>;
284 |   using pointer = handle_type::pointer;
285 | 
286 |   context (pointer p, retain_object_t) :
287 |     context(p)
288 |   { handle.get_deleter().increment(handle.get()); }
289 | 
290 |   context (pointer p) : handle(p) { }
291 | 
292 |   context (context const& that) :
293 |     handle(that.handle.get())
294 |   { handle.get_deleter().increment(handle.get()) }
295 | 
296 |   context& operator = (context const& that) {
297 |     context(that.handle.get(), retain).swap(*this);
298 |     return *this;
299 |   }
300 | 
301 |   void swap (context& that) noexcept { handle.swap(that); }
302 |     
303 | private:
304 |   handle_type handle;
305 | };
306 | 
307 | ```
308 | 
309 | As we can see, using `retain_ptr` saves effort, allowing us in most cases to
310 | simply rely on the "rule of zero" for constructor management. It will also not
311 | confuse/terrify maintainers of code bases where objects construct a
312 | `unique_ptr` with the raw pointer of another (and *unique ownership* is not
313 | transferred).
314 | 
315 | # Examples # {#examples}
316 | 
317 | Some C APIs that would benefit from `retain_ptr<T>` are
318 | 
319 |  * OpenCL
320 |  * Mono (Assembly and Image types)
321 |  * CPython
322 |  * ObjC Runtime
323 |  * Grand Central Dispatch
324 | 
325 | Inside the [implementation|github] repository is an example of using
326 | `retain_ptr` with Python.
327 | 
328 | Note: Remember to implement a non-atomic `shared_ptr` (call it `rc<T>`)
329 | 
330 | # Technical Specification # {#specification}
331 | 
332 | A *retain pointer* is an object that extends the lifetime of another object
333 | (which in turn manages its own dispostion) and manages that other object
334 | through a pointer. Specifically, a retain pointer is an object *r* that stores
335 | a pointer to a second object *p* and will cease to extend the lifetime of *p*
336 | when *r* is itself destroyed (e.g., when leaving a block scope). In this
337 | context, *r* is said to *retain* ``p``, and *p* is said to be a *self disposing
338 | object*.
339 | 
340 | When *p*'s lifetime has reached its end, *p* will dispose of itself as it sees
341 | fit. The conditions regarding *p*'s lifetime is handled by some count *c* that
342 | *p* comprehends, but is otherwise not directly accessible to *r*.
343 | 
344 | The mechanism by which *r* retains and manages the lifetime of *p* is known as
345 | *p*'s associated *retainer*, a stateless object that provides mechanisms for
346 | *r* to increment, decrement, and (optionally) provide access to *c*. In this
347 | context, *r* is able to *increment* ``c``, *decrement* ``c``, or access the *c*
348 | of *p*.
349 | 
350 | Let the notation *r.p* denote the pointer stored by *r*. Upon request, *r* can
351 | explicitly choose to increment *c* when *r.p* is replaced.
352 | 
353 | Additionally, *r* can, upon request, *transfer ownership* to another retain
354 | pointer *r2*. Upon completion of such a transfer, the following postconditions
355 | hold:
356 | 
357 |  - *r2.p* is equal to the pre-transfer *r.p*, and
358 |  - *r.p* is equal to ``nullptr``
359 | 
360 | Furthermore, *r* can, upon request, *extend ownership* to another retain
361 | pointer *r2*. Upon completion of such an extension, the following
362 | postconditions hold:
363 | 
364 |  - *r2.p* is equal to *r.p*
365 |  - *c* has been incremented by 1
366 | 
367 | Each object of a type ``U`` instantiated from the ``retain_ptr`` template
368 | specified in this proposal has the lifetime extension semantics specified
369 | above of a retain pointer. In partical satisfaction of these semantics, each
370 | such ``U`` is ``MoveConstructible``, ``MoveAssignable``, ``CopyConstructible``
371 | and ``CopyAssignable``. The template parameter ``T`` of ``retain_ptr`` may be
372 | an incomplete type. (*Note: The uses of* ``retain_ptr`` *include providing
373 | exception safety for self disposing objects, extending management of self
374 | disposing objects to a function, and returning self disposing objects from a
375 | function.*)
376 | 
377 | ```cpp
378 | class atomic_reference_count<T>;
379 | class reference_count<T>;
380 | 
381 | class retain_object_t;
382 | class adopt_object_t;
383 | 
384 | template <class T> struct retain_traits;
385 | 
386 | template <class T, class R = retain_traits<T>> class retain_ptr;
387 | 
388 | template <class T, class R>
389 | void swap (retain_ptr<T, R>& x, retain_ptr<T, R>& y) noexcept;
390 | 
391 | template <class T, class R, class U>
392 | retain_ptr<T, R> dynamic_pointer_cast (retain_ptr<U, R> const&) noexcept;
393 | 
394 | template <class T, class R, class U>
395 | retain_ptr<T, R> static_pointer_cast (retain_ptr<U, R> const&) noexcept;
396 | 
397 | template <class T, class R, class U>
398 | retain_ptr<T, R> const_pointer_cast (retain_ptr<U, R> const&) noexcept;
399 | 
400 | template <class T, class R, class U>
401 | retain_ptr<T, R> reinterpret_pointer_cast (retain_ptr<U, R> const&) noexcept;
402 | 
403 | template <class T, class R, class S=R>
404 | strong_ordering operator <=> (retain_ptr<T, R> const& x, retain_ptr<T, S> const& y) noexcept;
405 | template <class T, class R>
406 | strong_ordering operator <=> (retain_ptr<T, R> const& x, nullptr_t) noexcept;
407 | template <class T, class R>
408 | strong_ordering operator <=> (nullptr_t, retain_ptr<T, R> const& y) noexcept;
409 | ```
410 | 
411 | ## `atomic_reference_count<T>` and `reference_count<T>` ## {#wording-mixins}
412 | 
413 | ``atomic_reference_count<T>`` and ``reference_count<T>`` are mixin types,
414 | provided for user defined types that simply rely on ``new`` and ``delete`` to
415 | have their lifetime extended by ``retain_ptr``. The template parameter ``T`` is
416 | intended to be the type deriving from ``atomic_reference_count`` or
417 | ``reference_count`` (a.k.a. the curiously repeating template pattern, CRTP).
418 | 
419 | ```cpp
420 | template <class T>
421 | struct atomic_reference_count {
422 |   friend retain_traits<T>;
423 | protected:
424 |   atomic_reference_count () = default;
425 | private:
426 |   atomic<uint_least64_t> count { 1 }; // provided for exposition
427 | };
428 | 
429 | template <class T>
430 | struct reference_count {
431 |   friend retain_traits<T>;
432 | protected:
433 |   reference_count () = default;
434 | private:
435 |   uint_least64_t count { 1 }; // provided for exposition
436 | };
437 | ```
438 | 
439 | ## `retain_object_t` and `adopt_object_t` ## {#wording-sentinels}
440 | 
441 | ``retain_object_t`` and ``adopt_object_t`` are sentinel types, with constexpr
442 | instances ``retain_object`` and ``adopt_object`` respectively.
443 | 
444 | ```cpp
445 | namespace std {
446 |   struct retain_object_t { constexpr retain_object_t () = default; };
447 |   struct adopt_object_t { constexpr adopt_object_t () = default; };
448 |   constexpr retain_object_t retain_object { };
449 |   constexpr adopt_object_t adopt_object { };
450 | }
451 | ```
452 | 
453 | ## `retain_traits<T>` ## {#wording-traits}
454 | 
455 | The class template `retain_traits` serves the default traits object for the
456 | class template `retain_ptr`. Unless `retain_traits` is specialized for a
457 | specific type, the template parameter `T` must inherit from either
458 | `atomic_reference_count<T>` or `reference_count`. In the event that
459 | `retain_traits` is specialized for a type, the template parameter `T` may be
460 | an incomplete type.
461 | 
462 | ```cpp
463 | namespace std {
464 |   template <class T> struct retain_traits {
465 |     static void increment (atomic_reference_count<T>*) noexcept;
466 |     static void decrement (atomic_reference_count<T>*) noexcept;
467 |     static long use_count (atomic_reference_count<T>*) noexcept;
468 | 
469 |     static void increment (reference_count<T>*) noexcept;
470 |     static void decrement (reference_count<T>*) noexcept;
471 |     static long use_count (reference_count<T>*) noexcept;
472 |   };
473 | }
474 | ```
475 | 
476 | > `static void increment (atomic_reference_count<T>* ptr) noexcept;`
477 | > <br /><sup>1</sup> Effects: Increments the internal reference count for *ptr*
478 | > with `memory_order::relaxed`
479 | > <br /><sup>2</sup> Postcondition: `ptr->count` has been incremented by 1.
480 | 
481 | > `static void decrement (atomic_reference_count<T>* ptr) noexcept;`
482 | > <br /><sup>1</sup> Effects: Decrements the internal reference count for *ptr*
483 | > with `memory_order::acq_rel`. If the internal reference count of *ptr*
484 | > reaches 0, it is disposed of via ``delete``.
485 | 
486 | > `static long use_count (atomic_reference_count<T>* ptr) noexcept;`
487 | > <br /><sup>1</sup> Returns: The internal reference count for *ptr* with
488 | > `memory_order::acquire`.
489 | 
490 | > `static void increment (reference_count<T>* ptr) noexcept;`
491 | > <br /><sup>1</sup> Effects: Increments the internal reference count for *ptr*
492 | > by 1.
493 | 
494 | > `static void decrement (reference_count<T>* ptr) noexcept;`
495 | > <br /><sup>1</sup> Effects: Decrements the internal reference count for *ptr*
496 | > by 1. If the count reaches 0, *ptr* is disposed of via `delete`.
497 | 
498 | > `static long use_count (reference_count<T>* ptr) noexcept;`
499 | > <br /><sup>1</sup> Returns: The reference count for *ptr*.
500 | 
501 | ## `retain_ptr<T>` ## {#wording-pointer}
502 | 
503 | The default type for the template parameter `R` is `retain_traits`. A
504 | client supplied template argument `R` shall be an object with non-member
505 | functions for which, given a `ptr` of type `retain_ptr<T, R>::pointer`, the
506 | expressions `R::increment(ptr)` and `R::decrement(ptr)` are valid and has the
507 | effect of retaining or disposing of the pointer as appropriate for that
508 | retainer.
509 | 
510 | If the *qualified-id* `R::pointer` is valid and denotes a type, then
511 | `retain_ptr<T, R>::pointer` shall be synonymous with `R::pointer`. Otherwise
512 | `retain_ptr<T, R>::pointer` shall be a synonym for `element_type*`. The type
513 | `retain_ptr<T, R>::pointer` shall satisfy the requirements of
514 | *NullablePointer*.
515 | 
516 | ```cpp
517 | template <class T, class R=retain_traits<T>>
518 | struct retain_ptr {
519 |   using element_type = T;
520 |   using traits_type = R;
521 |   using pointer = /* see below */
522 | 
523 |   retain_ptr (pointer, retain_object_t) noexcept(/* see below */);
524 |   retain_ptr (pointer, adopt_object_t);
525 |   explicit retain_ptr (pointer) noexcept(/* see below */);
526 |   retain_ptr (nullptr_t) noexcept;
527 | 
528 |   retain_ptr (retain_ptr const&) noexcept(/* see below */);
529 |   retain_ptr (retain_ptr&&) noexcept;
530 |   retain_ptr () noexcept;
531 |   ~retain_ptr () noexcept(/* see below */);
532 | 
533 |   retain_ptr& operator = (retain_ptr const&) noexcept(/* see below */);
534 |   retain_ptr& operator = (retain_ptr&&) noexcept;
535 |   retain_ptr& operator = (nullptr_t) noexcept;
536 | 
537 |   void swap (retain_ptr&) noexcept;
538 | 
539 |   explicit operator pointer () const noexcept;
540 |   explicit operator bool () const noexcept;
541 | 
542 |   element_type& operator * () const noexcept;
543 |   pointer operator -> () const noexcept;
544 |   pointer get () const noexcept;
545 | 
546 |   long use_count () const noexcept(/* see below */);
547 | 
548 |   [[nodiscard]] pointer detach () noexcept;
549 | 
550 |   void reset (pointer, retain_object_t) noexcept(/* see below */);
551 |   void reset (pointer, adopt_object_t) noexcept(/* see below */);
552 |   void reset (pointer p = pointer { }) noexcept(/* see below */);
553 | };
554 | ```
555 | 
556 | ### `retain_ptr` constructors ### {#wording-pointer-ctor}
557 | 
558 | <blockquote>
559 | ```cpp
560 | retain_ptr (pointer p, retain_object_t);
561 | ```
562 | </blockquote>
563 | 
564 | *Effects*: Constructs a `retain_ptr` that retains `p`, initializing the stored
565 | pointer with `p`, and increments the reference count of `p` if `p != nullptr`
566 | by way of `traits_type::increment`.
567 | 
568 | *Postconditions*: `get() == p`
569 | 
570 | *Remarks*: If an exception is thrown during increment, this constructor will
571 | have no effect.
572 | 
573 | <blockquote>
574 | ```cpp
575 | retain_ptr (pointer p, adopt_object_t) noexcept;
576 | ```
577 | </blockquote>
578 | 
579 | *Effects*: Constructs a `retain_ptr` that adopts `p`, initializing the stored
580 | pointer with `p`.
581 | 
582 | *Postconditions*: `get() == p`
583 | 
584 | *Remarks*: `p`'s refrence count remains untouched.
585 | 
586 | <blockquote>
587 | ```cpp
588 | explicit retain_ptr (pointer p);
589 | ```
590 | </blockquote>
591 | 
592 | *Effects*: Constructs a `retain_ptr` by delegating to another `retain_ptr`
593 | constructor via `traits_type::default_action`. If `traits_type::default_action`
594 | does not exist, `retain_ptr` is constructed as if by `retain_ptr(p,
595 | adopt_object_t)`.
596 | 
597 | *Postconditions*: `get() == p`
598 | 
599 | *Remarks*: If an exception is thrown, this constructor will have no effect.
600 | 
601 | <blockquote>
602 | ```cpp
603 | retain_ptr () noexcept;
604 | ```
605 | </blockquote>
606 | 
607 | *Effects*: Constructs a `retain_ptr` object that retains nothing,
608 | value-initializing the stored pointer.
609 | 
610 | *Postconditions*: `get() == nullptr`
611 | 
612 | <blockquote>
613 | ```cpp
614 | retain_ptr(retain_ptr const& r);
615 | ```
616 | </blockquote>
617 | 
618 | *Effects*: Constructs a `retain_ptr` by extending management from `r` to
619 | `*this`. The stored pointer's reference count is incremented.
620 | 
621 | *Postconditions*: `get() == r.get()`
622 | 
623 | *Remarks*: If an exception is thrown, this constructor will have no effect.
624 | 
625 | <blockquote>
626 | ```cpp
627 | retain_ptr(retain_ptr&& r) noexcept;
628 | ```
629 | </blockquote>
630 | 
631 | *Effects*: Constructs a `retain_ptr` by transferring management from `r` to
632 | `*this`. The stored pointer's reference count remains untouched.
633 | 
634 | *Postconditions*: `get()` yields the value `r.get()` yielded before the
635 | construction.
636 | 
637 | ### `retain_ptr` destructor ### {#wording-pointer-dtor}
638 | 
639 | <blockquote>
640 | ```cpp
641 | ~retain_ptr();
642 | ```
643 | </blockquote>
644 | 
645 | *Effects*: If `get() == nullptr`, there are no effects. Otherwise,
646 | `traits_type::decrement(get())`.
647 | 
648 | ### `retain_ptr` assignment ### {#wording-pointer-assignment}
649 | 
650 | <blockquote>
651 | ```cpp
652 | retain_ptr& operator = (retain_ptr const& r);
653 | ```
654 | </blockquote>
655 | 
656 | *Effects*: Extends ownership from `r` to `*this` as if by calling
657 | `reset(r.get(), retain)`.
658 | *Returns*: `*this`
659 | 
660 | <blockquote>
661 | ```cpp
662 | retain_ptr& operator = (retain_ptr&& r) noexcept;
663 | ```
664 | </blockquote>
665 | 
666 | *Effects*: Transfers ownership from `r` to `*this` as if by calling
667 | `reset(r.detach())`
668 | *Returns*: `*this`
669 | 
670 | <blockquote>
671 | ```cpp
672 | retain_ptr& operator = (nullptr_t) noexcept;
673 | ```
674 | </blockquote>
675 | 
676 | *Effects*: `reset()`
677 | *Postconditions*: `get() == nullptr`
678 | *Returns*: `*this`
679 | 
680 | ### `retain_ptr` observers ### {#wording-pointer-observers}
681 | 
682 | <blockquote>
683 | ```cpp
684 | element_type& operator * () const noexcept;
685 | ```
686 | </blockquote>
687 | 
688 | *Requires*: `get() != nullptr`
689 | *Returns*: `*get()`
690 | 
691 | <blockquote>
692 | ```cpp
693 | pointer operator -> () const noexcept;
694 | ```
695 | </blockquote>
696 | 
697 | *Requires*: `get() != nullptr`
698 | *Returns*: `get()`
699 | *Note*: Use typically requires that `element_type` be a complete type.
700 | 
701 | <blockquote>
702 | ```cpp
703 | pointer get () const noexcept;
704 | ```
705 | </blockquote>
706 | 
707 | *Returns*: The stored pointer
708 | 
709 | <blockquote>
710 | ```cpp
711 | explicit operator pointer () const noexcept;
712 | ```
713 | </blockquote>
714 | 
715 | *Returns*: `get()`
716 | 
717 | <blockquote>
718 | ```cpp
719 | explicit operator bool () const noexcept;
720 | ```
721 | </blockquote>
722 | 
723 | *Returns*: `get() != nullptr`
724 | 
725 | <blockquote>
726 | ```cpp
727 | long use_count () const;
728 | ```
729 | </blockquote>
730 | 
731 | *Returns*: Value representing the current reference count of the current stored
732 | pointer. If `traits_type::use_count(get())` is not a valid expression, `-1` is
733 | returned. If `get() == nullptr`, `0` is returned.
734 | 
735 | *Remarks*: Unless otherwise specified, the value returned should be considered
736 | stale.
737 | 
738 | ### `retain_ptr` modifiers ### {#wording-pointer-modifiers}
739 | 
740 | <blockquote>
741 | ```cpp
742 | [[nodiscard]] pointer detach () noexcept;
743 | ```
744 | </blockquote>
745 | 
746 | *Postconditions*: `get() == nullptr`
747 | *Returns*: The value `get()` had at the start of the call to `detach()`.
748 | 
749 | <blockquote>
750 | ```cpp
751 | void reset (pointer p, retain_object_t);
752 | ```
753 | </blockquote>
754 | 
755 | *Effects*: Assigns `p` to the stored pointer, and then if the old value of
756 | stored pointer `old_p`, was not equal to `nullptr`, calls
757 | `traits_type::decrement`. Then if `p` is not equal to `nullptr`,
758 | `traits_type::increment` is called.
759 | *Postconditions*: `get() == p`
760 | 
761 | <blockquote>
762 | ```cpp
763 | void reset(pointer p, adopt_object_t);
764 | ```
765 | </blockquote>
766 | 
767 | *Effects*: Assigns `p` to the stored pointer, and then if the old value of
768 | stored pointer `old_p`, was not equal to `nullptr`, calls
769 | `traits_type::decrement`.
770 | *Postconditions*: `get() == p`
771 | 
772 | <blockquote>
773 | ```cpp
774 | void reset (pointer p = pointer { })
775 | ```
776 | </blockquote>
777 | 
778 | *Effects*: Delegates assignment of `p` to the stored pointer via `reset(p,
779 | traits_type::default_action())`.
780 | *Postconditions*: `get() == p`
781 | 
782 | <blockquote>
783 | ```cpp
784 | void swap (retain_ptr& r) noexcept;
785 | ```
786 | </blockquote>
787 | 
788 | *Effects*: Invokes `swap` on the stored pointers of `*this` and `r`.
789 | 
790 | 
791 | ### `retain_ptr` specialized algorithms ### {#wording-pointer-algorithms}
792 | 
793 | <blockquote>
794 | ```cpp
795 | template <class T, class R>
796 | void swap (retain_ptr<T, R>& x, retain_ptr<T, R>& y) noexcept;
797 | ```
798 | </blockquote>
799 | 
800 | *Effects*: Calls `x.swap(y)`
801 | 
802 | <blockquote>
803 | ```cpp
804 | template <class T, class R>
805 | auto operator <=> (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept = default;
806 | ```
807 | </blockquote>
808 | 
809 | *Returns*: `x.get() <=> y.get()`
810 | 
811 | <blockquote>
812 | ```cpp
813 | template <class T, class R>
814 | auto operator <=> (retain_ptr<T, R> const&, nullptr_t) noexcept = default;
815 | ```
816 | </blockquote>
817 | 
818 | *Returns*: `x.get() <=> nullptr`
819 | 
820 | <blockquote>
821 | ```cpp
822 | template <class T, class R>
823 | strong_ordering operator <=> (nullptr_t, retain_ptr<T, R> const& y) noexcept;
824 | ```
825 | </blockquote>
826 | 
827 | *Returns*: `nullptr <=> y.get()`
828 | 
829 | <pre class=biblio>
830 | {
831 |   "implementation": {
832 |     "title": "retain_ptr",
833 |     "authors": [ "Isabella Muerte" ],
834 |     "href": "https://github.com/slurps-mad-rips/retain-ptr"
835 |   }
836 | }
837 | </pre>
838 | 


--------------------------------------------------------------------------------
/proposal/pygments.css:
--------------------------------------------------------------------------------
 1 | .hll { background-color: #ffffcc }
 2 | .c { color: #8f5902; font-style: italic } /* Comment */
 3 | .err { color: #a40000; border: 1px solid #ef2929 } /* Error */
 4 | .g { color: #000000 } /* Generic */
 5 | .k { color: #204a87; font-weight: bold } /* Keyword */
 6 | .l { color: #000000 } /* Literal */
 7 | .n { color: #000000 } /* Name */
 8 | .o { color: #ce5c00; font-weight: bold } /* Operator */
 9 | .x { color: #000000 } /* Other */
10 | .p { color: #000000; font-weight: bold } /* Punctuation */
11 | .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */
12 | .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */
13 | .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */
14 | .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */
15 | .c1 { color: #8f5902; font-style: italic } /* Comment.Single */
16 | .cs { color: #8f5902; font-style: italic } /* Comment.Special */
17 | .gd { color: #a40000 } /* Generic.Deleted */
18 | .ge { color: #000000; font-style: italic } /* Generic.Emph */
19 | .gr { color: #ef2929 } /* Generic.Error */
20 | .gh { color: #000080; font-weight: bold } /* Generic.Heading */
21 | .gi { color: #00A000 } /* Generic.Inserted */
22 | .go { color: #000000; font-style: italic } /* Generic.Output */
23 | .gp { color: #8f5902 } /* Generic.Prompt */
24 | .gs { color: #000000; font-weight: bold } /* Generic.Strong */
25 | .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
26 | .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */
27 | .kc { color: #204a87; font-weight: bold } /* Keyword.Constant */
28 | .kd { color: #204a87; font-weight: bold } /* Keyword.Declaration */
29 | .kn { color: #204a87; font-weight: bold } /* Keyword.Namespace */
30 | .kp { color: #204a87; font-weight: bold } /* Keyword.Pseudo */
31 | .kr { color: #204a87; font-weight: bold } /* Keyword.Reserved */
32 | .kt { color: #204a87; font-weight: bold } /* Keyword.Type */
33 | .ld { color: #000000 } /* Literal.Date */
34 | .m { color: #0000cf; font-weight: bold } /* Literal.Number */
35 | .s { color: #4e9a06 } /* Literal.String */
36 | .na { color: #c4a000 } /* Name.Attribute */
37 | .nb { color: #204a87 } /* Name.Builtin */
38 | .nc { color: #000000 } /* Name.Class */
39 | .no { color: #000000 } /* Name.Constant */
40 | .nd { color: #5c35cc; font-weight: bold } /* Name.Decorator */
41 | .ni { color: #ce5c00 } /* Name.Entity */
42 | .ne { color: #cc0000; font-weight: bold } /* Name.Exception */
43 | .nf { color: #000000 } /* Name.Function */
44 | .nl { color: #f57900 } /* Name.Label */
45 | .nn { color: #000000 } /* Name.Namespace */
46 | .nx { color: #000000 } /* Name.Other */
47 | .py { color: #000000 } /* Name.Property */
48 | .nt { color: #204a87; font-weight: bold } /* Name.Tag */
49 | .nv { color: #000000 } /* Name.Variable */
50 | .ow { color: #204a87; font-weight: bold } /* Operator.Word */
51 | .w { color: #f8f8f8; text-decoration: underline } /* Text.Whitespace */
52 | .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */
53 | .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */
54 | .mh { color: #0000cf; font-weight: bold } /* Literal.Number.Hex */
55 | .mi { color: #0000cf; font-weight: bold } /* Literal.Number.Integer */
56 | .mo { color: #0000cf; font-weight: bold } /* Literal.Number.Oct */
57 | .sb { color: #4e9a06 } /* Literal.String.Backtick */
58 | .sc { color: #4e9a06 } /* Literal.String.Char */
59 | .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */
60 | .s2 { color: #4e9a06 } /* Literal.String.Double */
61 | .se { color: #4e9a06 } /* Literal.String.Escape */
62 | .sh { color: #4e9a06 } /* Literal.String.Heredoc */
63 | .si { color: #4e9a06 } /* Literal.String.Interpol */
64 | .sx { color: #4e9a06 } /* Literal.String.Other */
65 | .sr { color: #4e9a06 } /* Literal.String.Regex */
66 | .s1 { color: #4e9a06 } /* Literal.String.Single */
67 | .ss { color: #4e9a06 } /* Literal.String.Symbol */
68 | .bp { color: #3465a4 } /* Name.Builtin.Pseudo */
69 | .vc { color: #000000 } /* Name.Variable.Class */
70 | .vg { color: #000000 } /* Name.Variable.Global */
71 | .vi { color: #000000 } /* Name.Variable.Instance */
72 | .il { color: #0000cf; font-weight: bold } /* Literal.Number.Integer.Long */
73 | 


--------------------------------------------------------------------------------
/proposal/style.css:
--------------------------------------------------------------------------------
  1 | /*
  2 | :Author: Chad Skeeters
  3 | :Contact: goobsoft@gmail.com
  4 | 
  5 | Stylesheet for use with Docutils/rst2html.
  6 | */
  7 | 
  8 | html {
  9 |   font-size: 100%;
 10 |   -webkit-text-size-adjust: 100%;
 11 |       -ms-text-size-adjust: 100%;
 12 | }
 13 | 
 14 | a:focus {
 15 |   outline: thin dotted #333;
 16 |   outline: 5px auto -webkit-focus-ring-color;
 17 |   outline-offset: -2px;
 18 | }
 19 | 
 20 | a:hover,
 21 | a:active {
 22 |   outline: 0;
 23 | }
 24 | 
 25 | sub,
 26 | sup {
 27 |   position: relative;
 28 |   font-size: 75%;
 29 |   line-height: 0;
 30 |   vertical-align: baseline;
 31 | }
 32 | 
 33 | sup {
 34 |   top: -0.5em;
 35 | }
 36 | 
 37 | sub {
 38 |   bottom: -0.25em;
 39 | }
 40 | 
 41 | img {
 42 |   width: auto\9;
 43 |   height: auto;
 44 |   max-width: 100%;
 45 |   vertical-align: middle;
 46 |   border: 0;
 47 |   -ms-interpolation-mode: bicubic;
 48 | }
 49 | 
 50 | @media print {
 51 |   * {
 52 |     color: #000 !important;
 53 |     text-shadow: none !important;
 54 |     background: transparent !important;
 55 |     box-shadow: none !important;
 56 |   }
 57 |   a,
 58 |   a:visited {
 59 |     text-decoration: underline;
 60 |   }
 61 |   a[href]:after {
 62 |     content: " (" attr(href) ")";
 63 |   }
 64 |   abbr[title]:after {
 65 |     content: " (" attr(title) ")";
 66 |   }
 67 |   .ir a:after,
 68 |   a[href^="javascript:"]:after,
 69 |   a[href^="#"]:after {
 70 |     content: "";
 71 |   }
 72 |   pre,
 73 |   blockquote {
 74 |     border: 1px solid #999;
 75 |     page-break-inside: avoid;
 76 |   }
 77 |   thead {
 78 |     display: table-header-group;
 79 |   }
 80 |   tr,
 81 |   img {
 82 |     page-break-inside: avoid;
 83 |   }
 84 |   img {
 85 |     max-width: 100% !important;
 86 |   }
 87 |   @page  {
 88 |     margin: 0.5cm;
 89 |   }
 90 |   h1 {
 91 |     page-break-before:always;
 92 |   }
 93 |   h1.title {
 94 |     page-break-before:avoid;
 95 |   }
 96 |   p,
 97 |   h2,
 98 |   h3 {
 99 |     orphans: 3;
100 |     widows: 3;
101 |   }
102 |   h2,
103 |   h3 {
104 |     page-break-after: avoid;
105 |   }
106 | }
107 | 
108 | body {
109 |   margin: 40px;
110 |   margin-right: auto;
111 |   margin-left: auto;
112 |   width: 960px;
113 |   font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
114 |   font-size: 14px;
115 |   line-height: 20px;
116 |   color: #333333;
117 |   background-color: #ffffff;
118 | }
119 | 
120 | a {
121 |   color: #0088cc;
122 |   text-decoration: none;
123 | }
124 | 
125 | a:hover,
126 | a:focus {
127 |   color: #005580;
128 |   text-decoration: underline;
129 | }
130 | 
131 | .img-rounded {
132 |   -webkit-border-radius: 6px;
133 |      -moz-border-radius: 6px;
134 |           border-radius: 6px;
135 | }
136 | 
137 | .img-polaroid {
138 |   padding: 4px;
139 |   background-color: #fff;
140 |   border: 1px solid #ccc;
141 |   border: 1px solid rgba(0, 0, 0, 0.2);
142 |   -webkit-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
143 |      -moz-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
144 |           box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
145 | }
146 | 
147 | p {
148 |   margin: 0 0 10px;
149 | }
150 | 
151 | small {
152 |   font-size: 85%;
153 | }
154 | 
155 | strong {
156 |   font-weight: bold;
157 | }
158 | 
159 | em {
160 |   font-style: italic;
161 | }
162 | 
163 | cite {
164 |   font-style: normal;
165 | }
166 | 
167 | h1,
168 | h2,
169 | h3,
170 | h4,
171 | h5,
172 | h6 {
173 |   font-family: inherit;
174 |   font-weight: bold;
175 |   line-height: 30px;
176 |   color: inherit;
177 |   text-rendering: optimizelegibility;
178 | }
179 | h1 {
180 |   font-size: 2em;
181 |   padding-bottom:.2em;
182 |   border-bottom:1px solid grey;
183 | }
184 | h1.title {
185 |   padding-bottom:1em;
186 |   border-bottom:0px;
187 | }
188 | h2 {
189 |   font-size: 1.5em;
190 | }
191 | 
192 | h3 {
193 |   font-size: 1.3em;
194 |   font-family:Georgia, serif;
195 |   font-style:italic;
196 |   /*font-weight:normal;*/
197 | }
198 | 
199 | h4 {
200 |   font-size: 1.3em;
201 | }
202 | 
203 | h5 {
204 |   font-size: 1.2em;
205 | }
206 | 
207 | h6 {
208 |   font-size: 1.1em;
209 | }
210 | 
211 | ul,
212 | ol {
213 |   padding: 0;
214 |   margin: 0 0 10px 25px;
215 | }
216 | 
217 | ul ul,
218 | ul ol,
219 | ol ol,
220 | ol ul {
221 |   margin-bottom: 0;
222 | }
223 | 
224 | li {
225 |   line-height: 20px;
226 | }
227 | 
228 | dl {
229 |   margin-bottom: 20px;
230 | }
231 | 
232 | dt,
233 | dd {
234 |   line-height: 20px;
235 | }
236 | 
237 | dt {
238 |   font-weight: bold;
239 | }
240 | 
241 | dd {
242 |   margin-left: 10px;
243 | }
244 | 
245 | hr {
246 |   margin: 20px 0;
247 |   border: 0;
248 |   border-top: 1px solid #eeeeee;
249 |   border-bottom: 1px solid #ffffff;
250 | }
251 | 
252 | abbr[title],
253 | abbr[data-original-title] {
254 |   cursor: help;
255 |   border-bottom: 1px dotted #999999;
256 | }
257 | 
258 | abbr.initialism {
259 |   font-size: 90%;
260 |   text-transform: uppercase;
261 | }
262 | 
263 | blockquote {
264 |   padding: 0 0 0 15px;
265 |   margin: 0 0 20px;
266 |   border-left: 5px solid #eeeeee;
267 | }
268 | 
269 | blockquote p {
270 |   margin-bottom: 0;
271 |   font-size: 17.5px;
272 |   font-weight: 300;
273 |   line-height: 1.25;
274 | }
275 | 
276 | q:before,
277 | q:after,
278 | blockquote:before,
279 | blockquote:after {
280 |   content: "";
281 | }
282 | 
283 | address {
284 |   display: block;
285 |   margin-bottom: 20px;
286 |   font-style: normal;
287 |   line-height: 20px;
288 | }
289 | 
290 | code,
291 | pre {
292 |   padding: 0 3px 2px;
293 |   font-family: Consolas, "Courier New", monospace;
294 |   font-size: 12px;
295 |   color: #333333;
296 |   -webkit-border-radius: 3px;
297 |      -moz-border-radius: 3px;
298 |           border-radius: 3px;
299 | }
300 | 
301 | code {
302 |   padding: 2px 4px;
303 |   color: #d14;
304 |   white-space: nowrap;
305 |   background-color: #f7f7f9;
306 |   border: 1px solid #e1e1e8;
307 | }
308 | 
309 | pre {
310 |   display: block;
311 |   padding: 9.5px;
312 |   margin: 0 0 10px;
313 |   font-size: 13px;
314 |   line-height: 20px;
315 |   word-break: break-all;
316 |   word-wrap: break-word;
317 |   white-space: pre;
318 |   white-space: pre-wrap;
319 |   background-color: #f5f5f5;
320 |   border: 1px solid #ccc;
321 |   border: 1px solid rgba(0, 0, 0, 0.15);
322 |   -webkit-border-radius: 4px;
323 |      -moz-border-radius: 4px;
324 |           border-radius: 4px;
325 | }
326 | 
327 | pre.prettyprint {
328 |   margin-bottom: 20px;
329 | }
330 | 
331 | pre code {
332 |   padding: 0;
333 |   color: inherit;
334 |   white-space: pre;
335 |   white-space: pre-wrap;
336 |   background-color: transparent;
337 |   border: 0;
338 | }
339 | 
340 | .pre-scrollable {
341 |   max-height: 340px;
342 |   overflow-y: scroll;
343 | }
344 | 
345 | table {
346 |   max-width: 100%;
347 |   background-color: transparent;
348 |   border-collapse: collapse;
349 |   border-spacing: 0;
350 | }
351 | 
352 | .table {
353 |   width: 100%;
354 |   margin-bottom: 20px;
355 | }
356 | 
357 | .table th,
358 | .table td {
359 |   padding: 8px;
360 |   line-height: 20px;
361 |   text-align: left;
362 |   vertical-align: top;
363 |   border-top: 1px solid #dddddd;
364 | }
365 | 
366 | .table th {
367 |   font-weight: bold;
368 | }
369 | 
370 | .table thead th {
371 |   vertical-align: bottom;
372 | }
373 | 
374 | .table caption + thead tr:first-child th,
375 | .table caption + thead tr:first-child td,
376 | .table colgroup + thead tr:first-child th,
377 | .table colgroup + thead tr:first-child td,
378 | .table thead:first-child tr:first-child th,
379 | .table thead:first-child tr:first-child td {
380 |   border-top: 0;
381 | }
382 | 
383 | .table tbody + tbody {
384 |   border-top: 2px solid #dddddd;
385 | }
386 | 
387 | .table .table {
388 |   background-color: #ffffff;
389 | }
390 | 
391 | .table-condensed th,
392 | .table-condensed td {
393 |   padding: 4px 5px;
394 | }
395 | 
396 | .table-bordered {
397 |   border: 1px solid #dddddd;
398 |   border-collapse: separate;
399 |   *border-collapse: collapse;
400 |   border-left: 0;
401 |   -webkit-border-radius: 4px;
402 |      -moz-border-radius: 4px;
403 |           border-radius: 4px;
404 | }
405 | 
406 | .table-bordered th,
407 | .table-bordered td {
408 |   border-left: 1px solid #dddddd;
409 | }
410 | 
411 | .table-bordered caption + thead tr:first-child th,
412 | .table-bordered caption + tbody tr:first-child th,
413 | .table-bordered caption + tbody tr:first-child td,
414 | .table-bordered colgroup + thead tr:first-child th,
415 | .table-bordered colgroup + tbody tr:first-child th,
416 | .table-bordered colgroup + tbody tr:first-child td,
417 | .table-bordered thead:first-child tr:first-child th,
418 | .table-bordered tbody:first-child tr:first-child th,
419 | .table-bordered tbody:first-child tr:first-child td {
420 |   border-top: 0;
421 | }
422 | 
423 | .table-bordered thead:first-child tr:first-child > th:first-child,
424 | .table-bordered tbody:first-child tr:first-child > td:first-child,
425 | .table-bordered tbody:first-child tr:first-child > th:first-child {
426 |   -webkit-border-top-left-radius: 4px;
427 |           border-top-left-radius: 4px;
428 |   -moz-border-radius-topleft: 4px;
429 | }
430 | 
431 | .table-bordered thead:first-child tr:first-child > th:last-child,
432 | .table-bordered tbody:first-child tr:first-child > td:last-child,
433 | .table-bordered tbody:first-child tr:first-child > th:last-child {
434 |   -webkit-border-top-right-radius: 4px;
435 |           border-top-right-radius: 4px;
436 |   -moz-border-radius-topright: 4px;
437 | }
438 | 
439 | .table-bordered thead:last-child tr:last-child > th:first-child,
440 | .table-bordered tbody:last-child tr:last-child > td:first-child,
441 | .table-bordered tbody:last-child tr:last-child > th:first-child,
442 | .table-bordered tfoot:last-child tr:last-child > td:first-child,
443 | .table-bordered tfoot:last-child tr:last-child > th:first-child {
444 |   -webkit-border-bottom-left-radius: 4px;
445 |           border-bottom-left-radius: 4px;
446 |   -moz-border-radius-bottomleft: 4px;
447 | }
448 | 
449 | .table-bordered thead:last-child tr:last-child > th:last-child,
450 | .table-bordered tbody:last-child tr:last-child > td:last-child,
451 | .table-bordered tbody:last-child tr:last-child > th:last-child,
452 | .table-bordered tfoot:last-child tr:last-child > td:last-child,
453 | .table-bordered tfoot:last-child tr:last-child > th:last-child {
454 |   -webkit-border-bottom-right-radius: 4px;
455 |           border-bottom-right-radius: 4px;
456 |   -moz-border-radius-bottomright: 4px;
457 | }
458 | 
459 | .table-bordered tfoot + tbody:last-child tr:last-child td:first-child {
460 |   -webkit-border-bottom-left-radius: 0;
461 |           border-bottom-left-radius: 0;
462 |   -moz-border-radius-bottomleft: 0;
463 | }
464 | 
465 | .table-bordered tfoot + tbody:last-child tr:last-child td:last-child {
466 |   -webkit-border-bottom-right-radius: 0;
467 |           border-bottom-right-radius: 0;
468 |   -moz-border-radius-bottomright: 0;
469 | }
470 | 
471 | .table-bordered caption + thead tr:first-child th:first-child,
472 | .table-bordered caption + tbody tr:first-child td:first-child,
473 | .table-bordered colgroup + thead tr:first-child th:first-child,
474 | .table-bordered colgroup + tbody tr:first-child td:first-child {
475 |   -webkit-border-top-left-radius: 4px;
476 |           border-top-left-radius: 4px;
477 |   -moz-border-radius-topleft: 4px;
478 | }
479 | 
480 | .table-bordered caption + thead tr:first-child th:last-child,
481 | .table-bordered caption + tbody tr:first-child td:last-child,
482 | .table-bordered colgroup + thead tr:first-child th:last-child,
483 | .table-bordered colgroup + tbody tr:first-child td:last-child {
484 |   -webkit-border-top-right-radius: 4px;
485 |           border-top-right-radius: 4px;
486 |   -moz-border-radius-topright: 4px;
487 | }
488 | 
489 | .table-striped tbody > tr:nth-child(odd) > td,
490 | .table-striped tbody > tr:nth-child(odd) > th {
491 |   background-color: #f9f9f9;
492 | }
493 | 
494 | .table-hover tbody tr:hover > td,
495 | .table-hover tbody tr:hover > th {
496 |   background-color: #f5f5f5;
497 | }
498 | 
499 | table td[class*="span"],
500 | table th[class*="span"],
501 | .row-fluid table td[class*="span"],
502 | .row-fluid table th[class*="span"] {
503 |   display: table-cell;
504 |   float: none;
505 |   margin-left: 0;
506 | }
507 | 
508 | .hero-unit {
509 |   padding: 60px;
510 |   margin-bottom: 30px;
511 |   font-size: 18px;
512 |   font-weight: 200;
513 |   line-height: 30px;
514 |   color: inherit;
515 |   background-color: #eeeeee;
516 |   -webkit-border-radius: 6px;
517 |      -moz-border-radius: 6px;
518 |           border-radius: 6px;
519 | }
520 | 
521 | .hero-unit h1 {
522 |   margin-bottom: 0;
523 |   font-size: 60px;
524 |   line-height: 1;
525 |   letter-spacing: -1px;
526 |   color: inherit;
527 | }
528 | 
529 | .hero-unit li {
530 |   line-height: 30px;
531 | }
532 | 
533 | 
534 | /* rst2html default used to remove borders from tables and images */
535 | .borderless, table.borderless td, table.borderless th {
536 |   border: 0 }
537 | 
538 | table.borderless td, table.borderless th {
539 |   /* Override padding for "table.docutils td" with "! important".
540 |      The right padding separates the table cells. */
541 |   padding: 0 0.5em 0 0 ! important }
542 | 
543 | .first {
544 |   /* Override more specific margin styles with "! important". */
545 |   margin-top: 0 ! important }
546 | 
547 | .last, .with-subtitle {
548 |   margin-bottom: 0 ! important }
549 | 
550 | .hidden {
551 |   display: none }
552 | 
553 | a.toc-backref {
554 |   text-decoration: none ;
555 |   color: black }
556 | 
557 | blockquote.epigraph {
558 |   margin: 2em 5em ; }
559 | 
560 | dl.docutils dd {
561 |   margin-bottom: 0.5em }
562 | 
563 | object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
564 |   overflow: hidden;
565 | }
566 | 
567 | /* Uncomment (and remove this text!) to get bold-faced definition list terms
568 | dl.docutils dt {
569 |   font-weight: bold }
570 | */
571 | 
572 | div.abstract {
573 |   margin: 2em 5em }
574 | 
575 | div.abstract p.topic-title {
576 |   font-weight: bold ;
577 |   text-align: center }
578 | 
579 | div.admonition, div.attention, div.caution, div.danger, div.error,
580 | div.hint, div.important, div.note, div.tip, div.warning {
581 |   margin: 2em ;
582 |   border: medium outset ;
583 |   padding: 1em }
584 | 
585 | div.note, div.warning {
586 |   margin:1.5em 0px;
587 |   border: none;
588 | }
589 | 
590 | div.note p.admonition-title,
591 | div.warning p.admonition-title
592 | {
593 |   display:none;
594 | }
595 | 
596 | /* Clearfix
597 |  * http://css-tricks.com/snippets/css/clear-fix/
598 |  */
599 | 
600 | div.note:after,
601 | div.warning:after {
602 |   content:"";
603 |   display:table;
604 |   clear:both;
605 | }
606 | 
607 | div.note p:before,
608 | div.warning p:before {
609 |   display:block;
610 |   float:left;
611 |   font-size:4em;
612 |   line-height:1em;
613 |   margin-right:20px;
614 |   margin-left: 0em;
615 |   margin-top:-10px;
616 |   content:'\0270D'; /*handwriting*/
617 | }
618 | 
619 | div.warning p:before {
620 |   content:'\026A0'; /*warning*/
621 | }
622 | 
623 | div.admonition p.admonition-title, div.hint p.admonition-title,
624 | div.important p.admonition-title, div.note p.admonition-title,
625 | div.tip p.admonition-title {
626 |   font-weight: bold ;
627 |   font-family: sans-serif }
628 | 
629 | div.attention p.admonition-title, div.caution p.admonition-title,
630 | div.danger p.admonition-title, div.error p.admonition-title,
631 | div.warning p.admonition-title, .code .error {
632 |   color: red ;
633 |   font-weight: bold ;
634 |   font-family: sans-serif }
635 | 
636 | /* Uncomment (and remove this text!) to get reduced vertical space in
637 |    compound paragraphs.
638 | div.compound .compound-first, div.compound .compound-middle {
639 |   margin-bottom: 0.5em }
640 | 
641 | div.compound .compound-last, div.compound .compound-middle {
642 |   margin-top: 0.5em }
643 | */
644 | 
645 | div.dedication {
646 |   margin: 2em 5em ;
647 |   text-align: center ;
648 |   font-style: italic }
649 | 
650 | div.dedication p.topic-title {
651 |   font-weight: bold ;
652 |   font-style: normal }
653 | 
654 | div.figure {
655 |   margin-left: 2em ;
656 |   margin-right: 2em }
657 | 
658 | div.footer, div.header {
659 |   clear: both;
660 |   font-size: smaller }
661 | 
662 | div.line-block {
663 |   display: block ;
664 |   margin-top: 1em ;
665 |   margin-bottom: 1em }
666 | 
667 | div.line-block div.line-block {
668 |   margin-top: 0 ;
669 |   margin-bottom: 0 ;
670 |   margin-left: 1.5em }
671 | 
672 | div.sidebar {
673 |   margin: 0 0 0.5em 1em ;
674 |   border: medium outset ;
675 |   padding: 1em ;
676 |   background-color: #ffffee ;
677 |   width: 40% ;
678 |   float: right ;
679 |   clear: right }
680 | 
681 | div.sidebar p.rubric {
682 |   font-family: sans-serif ;
683 |   font-size: medium }
684 | 
685 | div.system-messages {
686 |   margin: 5em }
687 | 
688 | div.system-messages h1 {
689 |   color: red }
690 | 
691 | div.system-message {
692 |   border: medium outset ;
693 |   padding: 1em }
694 | 
695 | div.system-message p.system-message-title {
696 |   color: red ;
697 |   font-weight: bold }
698 | 
699 | div.topic {
700 |   margin: 2em }
701 | 
702 | h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
703 | h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
704 |   margin-top: 0.4em }
705 | 
706 | h1.title {
707 |   text-align: center }
708 | 
709 | h2.subtitle {
710 |   text-align: center }
711 | 
712 | hr.docutils {
713 |   width: 75% }
714 | 
715 | img.align-left, .figure.align-left, object.align-left {
716 |   clear: left ;
717 |   float: left ;
718 |   margin-right: 1em }
719 | 
720 | img.align-right, .figure.align-right, object.align-right {
721 |   clear: right ;
722 |   float: right ;
723 |   margin-left: 1em }
724 | 
725 | img.align-center, .figure.align-center, object.align-center {
726 |   display: block;
727 |   margin-left: auto;
728 |   margin-right: auto;
729 | }
730 | 
731 | .align-left {
732 |   text-align: left }
733 | 
734 | .align-center {
735 |   clear: both ;
736 |   text-align: center }
737 | 
738 | .align-right {
739 |   text-align: right }
740 | 
741 | /* reset inner alignment in figures */
742 | div.align-right {
743 |   text-align: inherit }
744 | 
745 | /* div.align-center * { */
746 | /*   text-align: left } */
747 | 
748 | ol.simple, ul.simple {
749 |   margin-bottom: 1em }
750 | 
751 | ol.arabic {
752 |   list-style: decimal }
753 | 
754 | ol.loweralpha {
755 |   list-style: lower-alpha }
756 | 
757 | ol.upperalpha {
758 |   list-style: upper-alpha }
759 | 
760 | ol.lowerroman {
761 |   list-style: lower-roman }
762 | 
763 | ol.upperroman {
764 |   list-style: upper-roman }
765 | 
766 | p.attribution {
767 |   text-align: right ;
768 |   margin-left: 50% }
769 | 
770 | p.caption {
771 |   font-style: italic }
772 | 
773 | p.credits {
774 |   font-style: italic ;
775 |   font-size: smaller }
776 | 
777 | p.label {
778 |   white-space: nowrap }
779 | 
780 | p.rubric {
781 |   font-weight: bold ;
782 |   font-size: larger ;
783 |   color: maroon ;
784 |   text-align: center }
785 | 
786 | p.sidebar-title {
787 |   font-family: sans-serif ;
788 |   font-weight: bold ;
789 |   font-size: larger }
790 | 
791 | p.sidebar-subtitle {
792 |   font-family: sans-serif ;
793 |   font-weight: bold }
794 | 
795 | p.topic-title {
796 |   font-weight: bold }
797 | 
798 | pre.address {
799 |   margin-bottom: 0 ;
800 |   margin-top: 0 ;
801 |   font: inherit }
802 | 
803 | pre.literal-block, pre.doctest-block, pre.math, pre.code {
804 |   margin-left: 2em ;
805 |   margin-right: 2em }
806 | 
807 | pre.code .ln { color: grey; } /* line numbers */
808 | pre.code, code { background-color: white }
809 | pre.code .comment, code .comment { color: #5C6576 }
810 | pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
811 | pre.code .literal.string, code .literal.string { color: #0C5404 }
812 | pre.code .name.builtin, code .name.builtin { color: #352B84 }
813 | pre.code .deleted, code .deleted { background-color: #DEB0A1}
814 | pre.code .inserted, code .inserted { background-color: #A3D289}
815 | 
816 | tt.docutils.literal { font-weight: bold }
817 | 
818 | span.classifier {
819 |   font-family: sans-serif ;
820 |   font-style: oblique }
821 | 
822 | span.classifier-delimiter {
823 |   font-family: sans-serif ;
824 |   font-weight: bold }
825 | 
826 | span.interpreted {
827 |   font-family: sans-serif }
828 | 
829 | span.option {
830 |   white-space: nowrap }
831 | 
832 | span.pre {
833 |   white-space: pre }
834 | 
835 | span.problematic {
836 |   color: red }
837 | 
838 | span.section-subtitle {
839 |   /* font-size relative to parent (h1..h6 element) */
840 |   font-size: 80% }
841 | 
842 | table.citation {
843 |   border-left: solid 1px gray;
844 |   margin-left: 1px }
845 | 
846 | table.docinfo {
847 |   margin: 2em 4em }
848 | 
849 | table.docutils {
850 |   margin-top: 0.5em ;
851 |   margin-bottom: 0.5em }
852 | 
853 | table.footnote {
854 |   border-left: solid 1px black;
855 |   margin-left: 1px }
856 | 
857 | table.docutils td, table.docutils th,
858 | table.docinfo td, table.docinfo th {
859 |   padding-left: 0.5em ;
860 |   padding-right: 0.5em ;
861 |   vertical-align: top }
862 | 
863 | table.docutils th.field-name, table.docinfo th.docinfo-name {
864 |   font-weight: bold ;
865 |   text-align: left ;
866 |   white-space: nowrap ;
867 |   padding-left: 0 }
868 | 
869 | h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
870 | h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
871 |   font-size: 100% }
872 | 
873 | ul.auto-toc {
874 |   list-style-type: none }
875 | 
876 | .code .pygments-hll { background-color: #ffffcc }
877 | .code .pygments-c { color: #60a0b0; font-style: italic } /* Comment */
878 | .code .pygments-err { border: 1px solid #FF0000 } /* Error */
879 | .code .pygments-k { color: #007020; font-weight: bold } /* Keyword */
880 | .code .pygments-o { color: #666666 } /* Operator */
881 | .code .pygments-cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
882 | .code .pygments-cp { color: #007020 } /* Comment.Preproc */
883 | .code .pygments-c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
884 | .code .pygments-cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
885 | .code .pygments-gd { color: #A00000 } /* Generic.Deleted */
886 | .code .pygments-ge { font-style: italic } /* Generic.Emph */
887 | .code .pygments-gr { color: #FF0000 } /* Generic.Error */
888 | .code .pygments-gh { color: #000080; font-weight: bold } /* Generic.Heading */
889 | .code .pygments-gi { color: #00A000 } /* Generic.Inserted */
890 | .code .pygments-go { color: #888888 } /* Generic.Output */
891 | .code .pygments-gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
892 | .code .pygments-gs { font-weight: bold } /* Generic.Strong */
893 | .code .pygments-gu { color: #800080; font-weight: bold } /* Generic.Subheading */
894 | .code .pygments-gt { color: #0044DD } /* Generic.Traceback */
895 | .code .pygments-kc { color: #007020; font-weight: bold } /* Keyword.Constant */
896 | .code .pygments-kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
897 | .code .pygments-kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
898 | .code .pygments-kp { color: #007020 } /* Keyword.Pseudo */
899 | .code .pygments-kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
900 | .code .pygments-kt { color: #902000 } /* Keyword.Type */
901 | .code .pygments-m { color: #40a070 } /* Literal.Number */
902 | .code .pygments-s { color: #4070a0 } /* Literal.String */
903 | .code .pygments-na { color: #4070a0 } /* Name.Attribute */
904 | .code .pygments-nb { color: #007020 } /* Name.Builtin */
905 | .code .pygments-nc { color: #0e84b5; font-weight: bold } /* Name.Class */
906 | .code .pygments-no { color: #60add5 } /* Name.Constant */
907 | .code .pygments-nd { color: #555555; font-weight: bold } /* Name.Decorator */
908 | .code .pygments-ni { color: #d55537; font-weight: bold } /* Name.Entity */
909 | .code .pygments-ne { color: #007020 } /* Name.Exception */
910 | .code .pygments-nf { color: #06287e } /* Name.Function */
911 | .code .pygments-nl { color: #002070; font-weight: bold } /* Name.Label */
912 | .code .pygments-nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
913 | .code .pygments-nt { color: #062873; font-weight: bold } /* Name.Tag */
914 | .code .pygments-nv { color: #bb60d5 } /* Name.Variable */
915 | .code .pygments-ow { color: #007020; font-weight: bold } /* Operator.Word */
916 | .code .pygments-w { color: #bbbbbb } /* Text.Whitespace */
917 | .code .pygments-mf { color: #40a070 } /* Literal.Number.Float */
918 | .code .pygments-mh { color: #40a070 } /* Literal.Number.Hex */
919 | .code .pygments-mi { color: #40a070 } /* Literal.Number.Integer */
920 | .code .pygments-mo { color: #40a070 } /* Literal.Number.Oct */
921 | .code .pygments-sb { color: #4070a0 } /* Literal.String.Backtick */
922 | .code .pygments-sc { color: #4070a0 } /* Literal.String.Char */
923 | .code .pygments-sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
924 | .code .pygments-s2 { color: #4070a0 } /* Literal.String.Double */
925 | .code .pygments-se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
926 | .code .pygments-sh { color: #4070a0 } /* Literal.String.Heredoc */
927 | .code .pygments-si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
928 | .code .pygments-sx { color: #c65d09 } /* Literal.String.Other */
929 | .code .pygments-sr { color: #235388 } /* Literal.String.Regex */
930 | .code .pygments-s1 { color: #4070a0 } /* Literal.String.Single */
931 | .code .pygments-ss { color: #517918 } /* Literal.String.Symbol */
932 | .code .pygments-bp { color: #007020 } /* Name.Builtin.Pseudo */
933 | .code .pygments-vc { color: #bb60d5 } /* Name.Variable.Class */
934 | .code .pygments-vg { color: #bb60d5 } /* Name.Variable.Global */
935 | .code .pygments-vi { color: #bb60d5 } /* Name.Variable.Instance */
936 | .code .pygments-il { color: #40a070 } /* Literal.Number.Integer.Long */
937 | 


--------------------------------------------------------------------------------
/tests/doctest.cxx:
--------------------------------------------------------------------------------
1 | #define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
2 | #include "doctest.hpp"
3 | 


--------------------------------------------------------------------------------
/tests/python.cxx:
--------------------------------------------------------------------------------
1 | #include "doctest.hpp"
2 | #include <python.hpp>
3 | 
4 | TEST_CASE("example") {
5 | }
6 | 


--------------------------------------------------------------------------------
/tests/usage_example.cxx:
--------------------------------------------------------------------------------
 1 | #include "doctest.hpp"
 2 | #include <sg14/memory.hpp>
 3 | 
 4 | template<class T>
 5 | struct instance_counted
 6 | {
 7 |   static long numInstances;
 8 |   instance_counted()
 9 |   {
10 |     numInstances++;
11 |   }
12 |   ~instance_counted()
13 |   {
14 |     numInstances--;
15 |   }
16 |   instance_counted(const instance_counted&)
17 |   {
18 |     numInstances++;
19 |   }
20 |   instance_counted& operator=(const instance_counted&)
21 |   {
22 |     numInstances++;
23 |   }
24 | };
25 | 
26 | template<class T>
27 | long instance_counted<T>::numInstances = 0;
28 | 
29 | template<class T>
30 | void test_basic_usage()
31 | {
32 |   using TPtr = sg14::retain_ptr<T>;
33 |   {
34 |     TPtr ptr{new T};
35 |     REQUIRE(T::numInstances == 1);
36 |     REQUIRE(ptr.use_count() == 1);
37 |     {
38 |       TPtr ptr2{ptr};
39 |       REQUIRE(T::numInstances == 1);
40 |       REQUIRE(ptr.use_count() == 2);
41 |       TPtr pt3{std::move(ptr2)};
42 |       REQUIRE(T::numInstances == 1);
43 |       REQUIRE(ptr.use_count() == 2);
44 |     }
45 |     REQUIRE(T::numInstances == 1);
46 |     REQUIRE(ptr.use_count() == 1);
47 |   }
48 |   REQUIRE(T::numInstances == 0);
49 | }
50 | 
51 | class Base: public sg14::reference_count<Base>, public instance_counted<Base>
52 | {};
53 | 
54 | TEST_CASE("base class")
55 | {
56 |   test_basic_usage<Base>();
57 | }
58 | 
59 | class Derived: public Base
60 | {};
61 | 
62 | TEST_CASE("derived class")
63 | {
64 |   test_basic_usage<Derived>();
65 | }
66 | 
67 | class ThreadSafeBase: public sg14::atomic_reference_count<ThreadSafeBase>, public instance_counted<ThreadSafeBase>
68 | {};
69 | 
70 | TEST_CASE("thread safe base class")
71 |   {
72 |   test_basic_usage<ThreadSafeBase>();
73 | }
74 | 
75 | class ThreadSafeDerived: public ThreadSafeBase
76 | {};
77 | 
78 | TEST_CASE("thread safe derived class")
79 | {
80 |   test_basic_usage<ThreadSafeDerived>();
81 | }
82 | 


--------------------------------------------------------------------------------