OpenVDB: nanovdb/util/HostBuffer.h File Reference

OpenVDB 9.1.0

Classes | Namespaces | Macros
HostBuffer.h File Reference

HostBuffer - a buffer that contains a shared or private bump pool to either externally or internally managed host memory. More...

`#include <stdint.h>`
`#include <cstdio>`
`#include <cstdlib>`
`#include <memory>`
`#include <mutex>`
`#include <unordered_set>`
`#include <cassert>`
`#include <sstream>`
`#include <cstring>`

Go to the source code of this file.

## Classes
struct | BufferTraits< BufferT >
class | HostBuffer
| This is a buffer that contains a shared or private pool to either externally or internally managed host memory. More...
struct | HostBuffer::Pool

## Namespaces
namespace | nanovdb

## Macros
#define | checkPtr(ptr, msg)

## Detailed Description

HostBuffer - a buffer that contains a shared or private bump pool to either externally or internally managed host memory.

Date
  April 20, 2021

This HostBuffer can be used in multiple ways, most of which are demonstrated in the examples below. Memory in the pool can be managed or unmanged (e.g. internal or external) and can be shared between multiple buffers or belong to a single buffer.

Example that uses HostBuffer::create inside io::readGrids to create a full self-managed buffer, i.e. not shared and without padding, per grid in the file.

auto handles = nanovdb::io::readGrids("file.nvdb");
nanovdb::io::readGrids
VecT< GridHandle< BufferT > > readGrids(const std::string &fileName, int verbose=0, const BufferT &buffer=BufferT())
Read all the grids in the file.
Definition: IO.h:655

Example that uses HostBuffer::createFull. Assuming you have a raw pointer to a NanoVDB grid of unknown type, this examples shows how to create its GridHandle which can be used to enquire about the grid type and meta data.

void *data;// pointer to a NanoVDB grid of unknown type
uint64_t size;// byte size of NanoVDB grid of unknown type
auto buffer = nanovdb::HostBuffer::createFull(size, data);
nanovdb::GridHandle<> gridHandle(std::move(buffer));
nanovdb::GridHandle
This class serves to manage a raw memory buffer of a NanoVDB Grid.
Definition: GridHandle.h:71
nanovdb::HostBuffer::createFull
static HostBuffer createFull(uint64_t bufferSize, void *data=nullptr)
Return a full buffer which satisfies: buffer.size == bufferSize, buffer.poolSize() == bufferSize,...
Definition: HostBuffer.h:462

Example that uses HostBuffer::createPool for internally managed host memory. Suppose you want to read multiple grids in multiple files, but reuse the same fixed sized memory buffer to both avoid memory fragmentation as well as exceeding the fixed memory ceiling!

auto pool = nanovdb::HostBuffer::createPool(1 << 30);// 1 GB memory pool
std::vector<std::string>> frames;// vector of grid names
for (int i=0; i<frames.size(); ++i) {
auto handles = nanovdb::io::readGrids(frames[i], 0, pool);// throws if grids in file exceed 1 GB
...
pool.reset();// clears all handles and resets the memory pool for reuse
}
nanovdb::HostBuffer::createPool
static HostBuffer createPool(uint64_t poolSize, void *data=nullptr)
Return a pool buffer which satisfies: buffer.size == 0, buffer.poolSize() == poolSize,...
Definition: HostBuffer.h:449

Example that uses HostBuffer::createPool for externally managed host memory. Note that in this example `handles` are allowed to outlive `pool` since they internally store a shared pointer to the memory pool. However `data` MUST outlive `handles` since the pool does not own its memory in this example.

const size_t poolSize = 1 << 30;// 1 GB
uint8_t *data = static_cast<uint8_t*>(std::malloc(size));// 1 GB buffer
auto pool = nanovdb::HostBuffer::createPool(poolSize, data);
auto handles1 = nanovdb::io::readGrids("file1.nvdb", 0, pool);
auto handles2 = nanovdb::io::readGrids("file2.nvdb", 0, pool);
....
std::free(data);

Example that uses HostBuffer::createPool for externally managed host memory. Note that in this example `handles` are allowed to outlive `pool` since they internally store a shared pointer to the memory pool. However `array` MUST outlive `handles` since the pool does not own its memory in this example.

const size_t poolSize = 1 << 30;// 1 GB
std::unique_ptr<uint8_t[]> array(new uint8_t[size]);// scoped buffer of 1 GB
auto pool = nanovdb::HostBuffer::createPool(poolSize, array.get());
auto handles = nanovdb::io::readGrids("file.nvdb", 0, pool);

## Macro Definition Documentation

## ◆ checkPtr

#define checkPtr | ( |  | ptr,
|  |  | msg
| ) |  |

Value:
{ \
ptrAssert((ptr), (msg), __FILE__, __LINE__); \
}