From 90231ed7e0bd53a39f08bf5d14d179a7e98d390e Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Fri, 27 Jan 2023 02:42:10 +0200 Subject: [PATCH] Document boost::core::memory_resource --- doc/changes.qbk | 10 +-- doc/core.qbk | 1 + doc/max_align.qbk | 2 +- doc/memory_resource.qbk | 139 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 147 insertions(+), 5 deletions(-) create mode 100644 doc/memory_resource.qbk diff --git a/doc/changes.qbk b/doc/changes.qbk index 3a63779..46e41b1 100644 --- a/doc/changes.qbk +++ b/doc/changes.qbk @@ -16,10 +16,12 @@ or C++ standard library type traits instead. * Marked `boost::ref` member functions and associated methods with `noexcept`. * Marked `boost::swap` function with `noexcept`, depending on whether the type supports a non-throwing swap operation. -* Added `boost::core::launder`, a portable implementation of `std::launder`. -* Added `BOOST_CORE_ALIGNOF`, a portable implementation of `alignof`. -* Added `boost::core::max_align_t`, a portable equivalent of `std::max_align_t`, and `boost::core::max_align`, the - alignment of `max_align_t`. +* Added [link core.launder `boost::core::launder`], a portable implementation of `std::launder`. +* Added [link core.alignof `BOOST_CORE_ALIGNOF`], a portable implementation of `alignof`. +* Added [link core.max_align `boost::core::max_align_t`], a portable equivalent of `std::max_align_t`, and + `boost::core::max_align`, the alignment of `max_align_t`. +* Added [link core.memory_resource `boost::core::memory_resource`], a portable equivalent of `std::pmr::memory_resource` + from C++17. [endsect] diff --git a/doc/core.qbk b/doc/core.qbk index 57e0eb0..3cddc75 100644 --- a/doc/core.qbk +++ b/doc/core.qbk @@ -59,6 +59,7 @@ criteria for inclusion is that the utility component be: [include launder.qbk] [include lightweight_test.qbk] [include max_align.qbk] +[include memory_resource.qbk] [include no_exceptions_support.qbk] [include noinit_adaptor.qbk] [include noncopyable.qbk] diff --git a/doc/max_align.qbk b/doc/max_align.qbk index 883a260..6a7eb9d 100644 --- a/doc/max_align.qbk +++ b/doc/max_align.qbk @@ -29,7 +29,7 @@ namespace core union max_align_t; -constexpr max_align = alignof(max_align_t); +constexpr std::size_t max_align = alignof(max_align_t); } // namespace core } // namespace boost diff --git a/doc/memory_resource.qbk b/doc/memory_resource.qbk new file mode 100644 index 0000000..fa172bb --- /dev/null +++ b/doc/memory_resource.qbk @@ -0,0 +1,139 @@ +[/ + Copyright 2023 Peter Dimov + Distributed under the Boost Software License, Version 1.0. + https://boost.org/LICENSE_1_0.txt +] + +[section:memory_resource memory_resource] + +[simplesect Authors] + +* Peter Dimov + +[endsimplesect] + +[section Header ] + +The header `` defines the class +`boost::core::memory_resource`, a portable equivalent of +`std::pmr::memory_resource` from C++17. + +This is not a complete implementation of the standard `` +header; for such, one should use Boost.Container. The abstract base class +is only provided by Core so that Boost libraries that provide and take +advantage of PMR facilities such as concrete implementations of memory +resources, or implementations of `polymorphic_allocator`, can interoperate. + +[section Synopsis] + +`` +namespace boost +{ +namespace core +{ + +class memory_resource +{ +public: + + virtual ~memory_resource() = default; + + [[nodiscard]] void* allocate( std::size_t bytes, std::size_t alignment = max_align ); + void deallocate( void* p, std::size_t bytes, std::size_t alignment = max_align ); + + bool is_equal( memory_resource const & other ) const noexcept; + +private: + + virtual void* do_allocate( std::size_t bytes, std::size_t alignment ) = 0; + virtual void do_deallocate( void* p, std::size_t bytes, std::size_t alignment ) = 0; + + virtual bool do_is_equal( memory_resource const& other ) const noexcept = 0; +}; + +inline bool operator==( memory_resource const& a, memory_resource const& b ) noexcept; +inline bool operator!=( memory_resource const& a, memory_resource const& b ) noexcept; + +} // namespace core +} // namespace boost +`` + +[endsect] + +[section `allocate`] + +`[[nodiscard]] void* allocate( std::size_t bytes, std::size_t alignment = max_align );` + +* *Returns:* `do_allocate( bytes, alignment )`. +* *Remarks:* Implicitly creates objects in the returned region of storage. + +[endsect] + +[section `deallocate`] + +`void deallocate( void* p, std::size_t bytes, std::size_t alignment = max_align );` + +* *Effects:* `do_deallocate( bytes, alignment )`. + +[endsect] + +[section `is_equal`] + +`bool is_equal( memory_resource const& other ) const noexcept;` + +* *Returns:* `do_is_equal( other )`. + +[endsect] + +[section `do_allocate`] + +`void* do_allocate( std::size_t bytes, std::size_t alignment ) = 0;` + +* *Remarks:* A derived class should implement this member function to return + a pointer to allocated storage of size at least `bytes` and alignment at + least `alignment`. +* *Throws:* An appropriate exception (by convention `std::bad_alloc` or + derived) when storage with the specified size and alignment could not be + obtained. + +[endsect] + +[section `do_deallocate`] + +`void do_deallocate( void* p, std::size_t bytes, std::size_t alignment ) = 0;` + +* *Remarks:* A derived class should implement this member function to deallocate + a region of storage previously allocated by `do_allocate`. +* *Throws:* Nothing. + +[endsect] + +[section `do_is_equal`] + +`bool do_is_equal( memory_resource const& other ) const noexcept = 0;` + +* *Remarks:* A derived class shall implement this function to return `true` if + memory allocated from `*this` can be deallocated from `other` and vice-versa, + otherwise `false`. + +[endsect] + +[section `operator==`] + +`bool operator==( memory_resource const& a, memory_resource const& b ) noexcept;` + +* *Returns:* `&a == &b || a.is_equal( b )`. + +[endsect] + +[section `operator!=`] + +`bool operator!=( memory_resource const& a, memory_resource const& b ) noexcept;` + +* *Returns:* `!( a == b )`. + +[endsect] + +[endsect] + +[endsect]