monotonic_resource

`monotonic_resource`

A dynamically allocating resource with a trivial deallocate.

Synopsis

Defined in header <boost/json/monotonic_resource.hpp>.

class monotonic_resource
    : public boost::container::pmr::memory_resource;

Member Functions

Name Description

Name	Description
`monotonic_resource` [constructor]	Constructor.
`operator=`	Copy assignment (deleted)
`release`	Release all allocated memory.
`~monotonic_resource` [destructor]	Destructor.

monotonic_resource [constructor]

Constructor.

operator=

Copy assignment (deleted)

release

Release all allocated memory.

~monotonic_resource [destructor]

Destructor.

Description

This memory resource is a special-purpose resource that releases allocated memory only when the resource is destroyed (or when release is called). It has a trivial deallocate function; that is, the metafunction is_deallocate_trivial returns true.

The resource can be constructed with an initial buffer. If there is no initial buffer, or if the buffer is exhausted, subsequent dynamic allocations are made from the system heap. The size of buffers obtained in this fashion follow a geometric progression.

The purpose of this resource is to optimize the use case for performing many allocations, followed by deallocating everything at once. This is precisely the pattern of memory allocation which occurs when parsing: allocation is performed for each parsed element, and when the the resulting value is no longer needed, the entire structure is destroyed. However, it is not suited for modifying the value after parsing is complete; reallocations waste memory, since the older buffer is not reclaimed until the resource is destroyed.

Example

This parses a JSON text into a value which uses a local stack buffer, then prints the result.

unsigned char buf[ 4000 ];
monotonic_resource mr( buf );

// Parse the string, using our memory resource
auto const jv = parse( "[1,2,3]", &mr );

// Print the JSON
std::cout << jv;

The total amount of memory dynamically allocated is monotonically increasing; That is, it never decreases.

Thread Safety

Members of the same instance may not be called concurrently.