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
--- | ---
`monotonic_resource` [constructor] | Constructors.
`operator=` | Assignment operator.
`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.

### See Also

https://en.wikipedia.org/wiki/Region-based_memory_management

Convenience header <boost/json.hpp>.

Edit this page