jsoncons/doc/ref/corelib/json/allocators.md at master · physycom/jsoncons

Allocators

The class basic_json has an Allocator template parameter and an allocator_type member that indicates that it is allocator aware. Allocator must be a Scoped Allocator, that is, an allocator that applies not only to a basic_json's data member, but also to its data member's elements. In particular, Allocator must be either a stateless allocator, a std::pmr::polymorphic_allocator, or a std::scoped_allocator_adaptor. Non-propagating stateful allocators, such as the Boost.Interprocess allocators, must be wrapped by a std::scoped_allocator_adaptor.

Every constructor has a version that accepts an allocator argument, this is required for allocator propogation. A long string, byte string, array or object makes use of the allocator argument to allocate storage. For the other data members (short string, number, boolean, or null) the allocator argument is ignored.

A long string, byte string, array and object data member all contain a pointer ptr obtained from an earlier call to allocate. ptr points to storage that contains both the data representing the long string, byte string, array or object, and the allocator used to allocate that storage. To later deallocate that storage, the allocator is retrieved with ptr->get_allocator().

Propagation

The allocator applies not only to a basic_json's data member, but also to its data member's elements. For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

std::string key = "key too long for short string";
std::string value = "string too long for short string";

jsoncons::pmr::json j{ jsoncons::json_object_arg, alloc };
assert(j.get_allocator().resource() == &pool);

j.try_emplace(key, value);

auto it = std::search(std::begin(buffer), std::end(buffer), key.begin(), key.end());
assert(it != std::end(buffer));
it = std::search(std::begin(buffer), std::end(buffer), value.begin(), value.end());
assert(it != std::end(buffer));

Copy construction

The copy constructor

Json j1(j);

constructs j1 from the contents of j. If j holds a long string, bytes string, array or object, copy construction applies allocator traits select_on_container_copy_construction to the allocator from j (since 0.178.0) For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

jsoncons::pmr::json j{ "String too long for short string", alloc };
assert(j.is_string());
assert(j.get_allocator().resource() == &pool);

jsoncons::pmr::json j1(j);
assert(j1 == j);
assert(j1.get_allocator() == std::allocator_traits<std::pmr::polymorphic_allocator<char>>::
    select_on_container_copy_construction(j.get_allocator()));
assert(j1.get_allocator() == std::pmr::polymorphic_allocator<char>{}); // expected result for pmr allocators

Allocator-extended copy construction

The allocator-extended copy constructor

Json j1(j, alloc);

constructs j1 from the contents of j using alloc as the allocator. If j holds a long string, bytes string, array or object, copy construction uses allocator alloc for allocating storage, otherwise alloc is ignored. For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

char buffer1[1024];
std::pmr::monotonic_buffer_resource pool1{ std::data(buffer1), std::size(buffer1) };
std::pmr::polymorphic_allocator<char> alloc1(&pool1);

jsoncons::pmr::json j{ "String too long for short string", alloc };
assert(j.is_string());
assert(j.get_allocator().resource() == &pool);

jsoncons::pmr::json j1(j, alloc1);
assert(j1 == j);
assert(j1.get_allocator().resource() == &pool1);

Move construction

The move constructor

Json j1(std::move(j));

constructs j1 by taking the contents of j, which has either a pointer or a trivially copyable value, and replaces it with null. For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

jsoncons::pmr::json j{ "String too long for short string", alloc};
assert(j.is_string());
assert(j.get_allocator().resource() == &pool);

jsoncons::pmr::json j1(std::move(j));
assert(j1.is_string());
assert(j1.get_allocator().resource() == &pool);
assert(j.is_null());

Allocator-extended move construction

The allocator-extended move constructor

Json j1(std::move(j), alloc);

constructs j1 with a copy of the data member j, using alloc as the allocator. For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

char buffer1[1024];
std::pmr::monotonic_buffer_resource pool1{ std::data(buffer1), std::size(buffer1) };
std::pmr::polymorphic_allocator<char> alloc1(&pool1);

jsoncons::pmr::json j{ "String too long for short string", alloc };
assert(j.is_string());
assert(j.get_allocator().resource() == &pool);

jsoncons::pmr::json j1(std::move(j), alloc1);
assert(j1.is_string());
assert(j1.get_allocator().resource() == &pool1);

Copy assignment

If the left side is a long string, byte string, array or object, uses its allocator, otherwise, if the right side is a long string, byte string, array or object, constructs a copy of the right side as if using copy construction, i.e. applies allocator traits select_on_container_copy_construction to the right side allocator. For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

char buffer1[1024];
std::pmr::monotonic_buffer_resource pool1{ std::data(buffer1), std::size(buffer1) };
std::pmr::polymorphic_allocator<char> alloc1(&pool1);

jsoncons::pmr::json j{ "String too long for short string", alloc };
assert(j.is_string());
assert(j.get_allocator().resource() == &pool);

// copy long string to number
jsoncons::pmr::json j1{10};
j1 = j;
assert(j1.is_string());
assert(j1.get_allocator() == std::allocator_traits<std::pmr::polymorphic_allocator<char>>::
    select_on_container_copy_construction(j.get_allocator()));
assert(j1.get_allocator() == std::pmr::polymorphic_allocator<char>{});

// copy long string to array
jsoncons::pmr::json j2{ jsoncons::json_array_arg, {1,2,3,4}, 
    jsoncons::semantic_tag::none, alloc1};
j2 = j;
assert(j2.is_string());
assert(j2.get_allocator().resource() == &pool1);

basic_json does not check allocator traits propagate_on_container_copy_assignment. In the case of arrays and objects, basic_json leaves it to the implementing types (by default std::vector) to conform to the traits.

Move assignment

If either j or j1 are a long string, byte string, array, or object, basic_json move assignment

j1 = std::move(j);

swaps the two data member values, such that two pointers are swapped or a pointer and a trivially copyable value are swapped. Otherwise, move assignment copies j's value to j1 and leaves j unchanged. For example:

char buffer[1024];
std::pmr::monotonic_buffer_resource pool{ std::data(buffer), std::size(buffer) };
std::pmr::polymorphic_allocator<char> alloc(&pool);

jsoncons::pmr::json j{ "String too long for short string", alloc };
assert(j.is_string());
assert(j.get_allocator().resource() == &pool);

jsoncons::pmr::json j1{10};
assert(j1.is_number());

j1 = std::move(j);
assert(j1.is_string());
assert(j1.get_allocator().resource() == &pool);
assert(j.is_number());

basic_json does not check allocator traits propagate_on_container_move_assignment. It simply swaps pointers, or a pointer and a trivial value, or copies a trivial value.

Fancy pointers

basic_json is compatible with boost boost::interprocess::offset_ptr, provided that the implementing containers for arrays and objects are also compatible. In the example below, boost containers are used.

#include <boost/interprocess/managed_shared_memory.hpp>
#include <boost/interprocess/containers/vector.hpp>
#include <boost/interprocess/allocators/allocator.hpp>
#include <boost/interprocess/containers/string.hpp>
#include <cstdlib> //std::system
#include <jsoncons/json.hpp>
#include <scoped_allocator>

using shmem_allocator = boost::interprocess::allocator<int,
    boost::interprocess::managed_shared_memory::segment_manager>;

using cust_allocator = std::scoped_allocator_adaptor<shmem_allocator>;

struct boost_sorted_policy 
{
    template <typename KeyT,typename Json>
    using object = jsoncons::sorted_json_object<KeyT,Json,boost::interprocess::vector>;

    template <typename Json>
    using array = jsoncons::json_array<Json,boost::interprocess::vector>;

    template <typename CharT,typename CharTraits,typename Allocator>
    using member_key = boost::interprocess::basic_string<CharT, CharTraits, Allocator>;
};

using cust_json = jsoncons::basic_json<char,boost_sorted_policy, cust_allocator>;

int main(int argc, char *argv[])
{
   typedef std::pair<double, int> MyType;

   if (argc == 1) // Parent process
   {  
      //Remove shared memory on construction and destruction
      struct shm_remove
      {
         shm_remove() { boost::interprocess::shared_memory_object::remove("MySharedMemory"); }
         ~shm_remove() noexcept { boost::interprocess::shared_memory_object::remove("MySharedMemory"); }
      } remover;

      //Construct managed shared memory
      boost::interprocess::managed_shared_memory segment(boost::interprocess::create_only, 
                                                         "MySharedMemory", 65536);

      //Initialize shared memory STL-compatible allocator
      const shmem_allocator alloc(segment.get_segment_manager());

      // Create json value with all dynamic allocations in shared memory

      cust_json* j = segment.construct<cust_json>("MyJson")(jsoncons::json_array_arg, alloc);
      j->push_back(10);

      cust_json o(jsoncons::json_object_arg, alloc);
      o.try_emplace("category", "reference");
      o.try_emplace("author", "Nigel Rees");
      o.insert_or_assign("title", "Sayings of the Century");
      o.insert_or_assign("price", 8.95);

      j->push_back(o);

      cust_json a(jsoncons::json_array_arg, 2,  cust_json(jsoncons::json_object_arg, alloc), 
          jsoncons::semantic_tag::none, alloc);
      a[0]["first"] = 1;

      j->push_back(a);

      std::pair<cust_json*, boost::interprocess::managed_shared_memory::size_type> res;
      res = segment.find<cust_json>("MyJson");

      std::cout << "Parent process:\n";
      std::cout << pretty_print(*(res.first)) << "\n\n";

      //Launch child process
      std::string s(argv[0]); s += " child ";
      if (0 != std::system(s.c_str()))
         return 1;

      //Check child has destroyed all objects
      if (segment.find<MyType>("MyJson").first)
         return 1;
   }
   else // Child process
   {
      //Open managed shared memory
      boost::interprocess::managed_shared_memory segment(boost::interprocess::open_only, 
          "MySharedMemory");

      std::pair<cust_json*, boost::interprocess::managed_shared_memory::size_type> res;
      res = segment.find<cust_json>("MyJson");

      if (res.first != nullptr)
      {
          std::cout << "Child process:\n";
          std::cout << pretty_print(*(res.first)) << "\n";
      }
      else
      {
          std::cout << "Result is null\n";
      }

      //We're done, delete all the objects
      segment.destroy<cust_json>("MyJson");
   }
   return 0;
}

Output:

Parent process:
[
    10,
    {
        "author": "Nigel Rees",
        "category": "reference",
        "price": 8.95,
        "title": "Sayings of the Century"
    },
    [
        {
            "first": 1
        },
        {}
    ]
]

Child process:
[
    10,
    {
        "author": "Nigel Rees",
        "category": "reference",
        "price": 8.95,
        "title": "Sayings of the Century"
    },
    [
        {
            "first": 1
        },
        {}
    ]
]