Exit Zen
38
:80
English
Default Memory Resource
6/230 · 23
39
:81
English
The default memory resource uses the global `operator new` and `operator delete` to allocate memory. This resource is not reference counted and has a non-trivial deallocate function. All default-constructed <<ref_storage_ptr>> objects reference the same memory resource:
152/2700 · 270
40
:91
English
Default-constructed library containers use the default memory resource:
17/710 · 71
41
:98
English
The default memory resource is well suited for general usage. It offers reasonable performance for parsing, and conservative memory usage for modification of the contents of containers.
48/1850 · 185
42
:103
English
This memory resource is not guaranteed to be the same as the result of `boost::container::pmr::get_default_resource`. It also cannot be changed with `boost::container::pmr::set_default_resource`.
121/1950 · 195
43
:107
English
Monotonic Resource
4/180 · 18
44
:108
English
Consider the pattern of memory allocation during parsing: when an array, object, or string is encountered the parser accumulates elements in its temporary storage area. When all of the elements are known, a single memory allocation is requested from the resource when constructing the value. Thus, parsing only allocates and constructs containers at their final size. Memory is not reallocated; that is, a memory buffer never needs to grow by allocating a new larger buffer and deallocating the previous buffer.
154/5110 · 511
45
:116
English
The <<ref_monotonic_resource>> optimizes this memory allocation pattern by allocating increasingly large blocks of global memory internally and parceling those blocks out in smaller pieces to fulfill allocation requests. It has a trivial deallocate function. The monotonic resource does not actually deallocate memory until the resource is destroyed. Thus, it is ideally suited for the use-case where JSON is parsed, and the resulting value is then inspected but not modified.
187/4760 · 476
46
:124
English
The resource to use when constructing values may be specified in calls to <<ref_parse>> as shown here:
58/1020 · 102
47
:132
English
Or, to parse into a value with shared ownership of the memory resource:
29/710 · 71
48
:139
English
A monotonic resource may be optionally constructed with an initial buffer to use first, before going to the heap. This allows the caller to use stack space and avoid dynamic allocations for most parsed JSON, falling back to dynamic allocation from the heap if the input JSON is larger than average, as shown here:
118/3130 · 313
49
:150
English
Static Resource
4/150 · 15
50
:151
English
A <<ref_static_resource>> constructs from a caller-provided buffer, and satisfies all memory allocation requests from the buffer. Once the buffer is exhausted, subsequent calls to allocate throw the exception `std::bad_alloc`. The resource offers a simple invariant: dynamic heap allocations are never performed.
147/3120 · 312
51
:157
English
To use the resource, construct it with a local buffer:
23/540 · 54
52
:164
English
Null Resource
3/130 · 13
53
:165
English
The function <<ref_get_null_resource>> returns a global instance of the null resource. This resource offers a simple invariant: all calls to allocate will throw the exception `std::bad_alloc`. An instance of the null resource can be used to make parsing guarantee that allocations from the heap are never made. This is explored in more detail in a later section.
162/3620 · 362
54
:171
English
Allocator Propagation
5/210 · 21
55
:172
English
The containers <<ref_array>>, <<ref_object>>, and <<ref_value>> all propagate the memory resource they were constructed with to child elements:
127/1430 · 143
56
:180
English
This propagation acts recursively, containers within containers will all have the resource propagated. Once a container is constructed, its memory resource can never be changed.
55/1770 · 177
57
:184
English
Resource Lifetime
6/170 · 17