boost/json/static_resource.hpp

0001 //
0002 // Copyright (c) 2020 Vinnie Falco (vinnie.falco@gmail.com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/json
0008 //
0009
0010 #ifndef BOOST_JSON_STATIC_RESOURCE_HPP
0011 #define BOOST_JSON_STATIC_RESOURCE_HPP
0012
0013 #include <boost/container/pmr/memory_resource.hpp>
0014 #include <boost/json/detail/config.hpp>
0015 #include <boost/json/is_deallocate_trivial.hpp>
0016 #include <cstddef>
0017
0018 namespace boost {
0019 namespace json {
0020
0021 #ifdef _MSC_VER
0022 #pragma warning(push)
0023 #pragma warning(disable: 4275) // non dll-interface class used as base for dll-interface class
0024 #endif
0025
0026 //----------------------------------------------------------
0027
0028 /** A resource using a caller-owned buffer, with a trivial deallocate
0029
0030     This memory resource is a special-purpose resource
0031     that releases allocated memory only when the resource
0032     is destroyed (or when @ref release is called).
0033     It has a trivial deallocate function; that is, the
0034     metafunction @ref is_deallocate_trivial returns `true`.
0035 \n
0036     The resource is constructed from a caller-owned buffer
0037     from which subsequent calls to allocate are apportioned.
0038     When a memory request cannot be satisfied from the
0039     free bytes remaining in the buffer, the allocation
0040     request fails with the exception `std::bad_alloc`.
0041 \n
0042     @par Example
0043
0044     This parses a JSON text into a value which uses a local
0045     stack buffer, then prints the result.
0046
0047     @code
0048
0049     unsigned char buf[ 4000 ];
0050     static_resource mr( buf );
0051
0052     // Parse the string, using our memory resource
0053     value const jv = parse( "[1,2,3]", &mr );
0054
0055     // Print the JSON
0056     std::cout << jv;
0057
0058     @endcode
0059
0060     @par Thread Safety
0061     Members of the same instance may not be
0062     called concurrently.
0063
0064     @see
0065         https://en.wikipedia.org/wiki/Region-based_memory_management
0066 */
0067 class
0068     BOOST_JSON_DECL
0069     BOOST_SYMBOL_VISIBLE
0070 static_resource final
0071     : public container::pmr::memory_resource
0072 {
0073     void* p_;
0074     std::size_t n_;
0075     std::size_t size_;
0076
0077 public:
0078     /// Copy constructor (deleted)
0079     static_resource(
0080         static_resource const&) = delete;
0081
0082     /// Copy assignment (deleted)
0083     static_resource& operator=(
0084         static_resource const&) = delete;
0085
0086     /** Constructor
0087
0088         This constructs the resource to use the specified
0089         buffer for subsequent calls to allocate. When the
0090         buffer is exhausted, allocate will throw
0091         `std::bad_alloc`.
0092
0093         @par Complexity
0094         Constant.
0095
0096         @par Exception Safety
0097         No-throw guarantee.
0098
0099         @param buffer The buffer to use.
0100         Ownership is not transferred; the caller is
0101         responsible for ensuring that the lifetime of
0102         the buffer extends until the resource is destroyed.
0103
0104         @param size The number of valid bytes pointed
0105         to by `buffer`.
0106     */
0107     /** @{ */
0108     static_resource(
0109         unsigned char* buffer,
0110         std::size_t size) noexcept;
0111
0112 #if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS)
0113     static_resource(
0114         std::byte* buffer,
0115         std::size_t size) noexcept
0116         : static_resource(reinterpret_cast<
0117             unsigned char*>(buffer), size)
0118     {
0119     }
0120 #endif
0121     /** @} */
0122
0123     /** Constructor
0124
0125         This constructs the resource to use the specified
0126         buffer for subsequent calls to allocate. When the
0127         buffer is exhausted, allocate will throw
0128         `std::bad_alloc`.
0129
0130         @par Complexity
0131         Constant.
0132
0133         @par Exception Safety
0134         No-throw guarantee.
0135
0136         @param buffer The buffer to use.
0137         Ownership is not transferred; the caller is
0138         responsible for ensuring that the lifetime of
0139         the buffer extends until the resource is destroyed.
0140     */
0141     /** @{ */
0142     template<std::size_t N>
0143     explicit
0144     static_resource(
0145         unsigned char(&buffer)[N]) noexcept
0146         : static_resource(&buffer[0], N)
0147     {
0148     }
0149
0150 #if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS)
0151     template<std::size_t N>
0152     explicit
0153     static_resource(
0154         std::byte(&buffer)[N]) noexcept
0155         : static_resource(&buffer[0], N)
0156     {
0157     }
0158 #endif
0159     /** @} */
0160
0161 #ifndef BOOST_JSON_DOCS
0162     // Safety net for accidental buffer overflows
0163     template<std::size_t N>
0164     static_resource(
0165         unsigned char(&buffer)[N], std::size_t n) noexcept
0166         : static_resource(&buffer[0], n)
0167     {
0168         // If this goes off, check your parameters
0169         // closely, chances are you passed an array
0170         // thinking it was a pointer.
0171         BOOST_ASSERT(n <= N);
0172     }
0173
0174 #ifdef __cpp_lib_byte
0175     // Safety net for accidental buffer overflows
0176     template<std::size_t N>
0177     static_resource(
0178         std::byte(&buffer)[N], std::size_t n) noexcept
0179         : static_resource(&buffer[0], n)
0180     {
0181         // If this goes off, check your parameters
0182         // closely, chances are you passed an array
0183         // thinking it was a pointer.
0184         BOOST_ASSERT(n <= N);
0185     }
0186 #endif
0187 #endif
0188
0189     /** Release all allocated memory.
0190
0191         This function resets the buffer provided upon
0192         construction so that all of the valid bytes are
0193         available for subsequent allocation.
0194
0195         @par Complexity
0196         Constant
0197
0198         @par Exception Safety
0199         No-throw guarantee.
0200     */
0201     void
0202     release() noexcept;
0203
0204 protected:
0205 #ifndef BOOST_JSON_DOCS
0206     void*
0207     do_allocate(
0208         std::size_t n,
0209         std::size_t align) override;
0210
0211     void
0212     do_deallocate(
0213         void* p,
0214         std::size_t n,
0215         std::size_t align) override;
0216
0217     bool
0218     do_is_equal(
0219         memory_resource const& mr
0220             ) const noexcept override;
0221 #endif
0222 };
0223
0224 #ifdef _MSC_VER
0225 #pragma warning(pop)
0226 #endif
0227
0228 template<>
0229 struct is_deallocate_trivial<
0230     static_resource>
0231 {
0232     static constexpr bool value = true;
0233 };
0234
0235 } // namespace json
0236 } // namespace boost
0237
0238 #endif