Queue for asynchronous output of grids to files or streams. More...

#include <Queue.h>

Public Types
enum	Status { UNKNOWN, PENDING, SUCCEEDED, FAILED }
	Status of a queued task. More...

using	Id = Index32
	ID number of a queued task or of a registered notification callback. More...

using	Notifier = std::function< void(Id, Status)>

Public Member Functions
	Queue (Index32 capacity=DEFAULT_CAPACITY)
	Construct a queue with the given capacity. More...

	~Queue ()
	Block until all queued tasks complete (successfully or unsuccessfully). More...

bool	empty () const
	Return `true` if the queue is empty. More...

Index32	size () const
	Return the number of tasks currently in the queue. More...

Index32	capacity () const
	Return the maximum number of tasks allowed in the queue. More...

void	setCapacity (Index32)
	Set the maximum number of tasks allowed in the queue. More...

Index32	timeout () const
	Return the maximum number of seconds to wait to queue a task when the queue is full. More...

void	setTimeout (Index32 seconds=DEFAULT_TIMEOUT)
	Set the maximum number of seconds to wait to queue a task when the queue is full. More...

Status	status (Id) const
	Return the status of the task with the given ID. More...

Id	addNotifier (Notifier)
	Register a function that will be called with a task's ID and status when that task completes, whether successfully or not. More...

void	removeNotifier (Id)
	Deregister the notifier with the given ID. More...

void	clearNotifiers ()
	Deregister all notifiers. More...

Id	writeGrid (GridBase::ConstPtr grid, const Archive &archive, const MetaMap &fileMetadata=MetaMap())
	Queue a single grid for output to a file or stream. More...

template<typename GridPtrContainer >
Id	write (const GridPtrContainer &grids, const Archive &archive, const MetaMap &fileMetadata=MetaMap())
	Queue a container of grids for output to a file. More...

template<>
Queue::Id	write (const GridCPtrVec &grids, const Archive &archive, const MetaMap &metadata)

Static Public Attributes
static const Index32	DEFAULT_CAPACITY = 100
	Default maximum queue length (see setCapacity()) More...

static const Index32	DEFAULT_TIMEOUT = 120
	Default maximum time in seconds to wait to queue a task when the queue is full (see setTimeout()) More...

Detailed Description

Queue for asynchronous output of grids to files or streams.

Warning: The queue holds shared pointers to grids. It is not safe to modify a grid that has been placed in the queue. Instead, make a deep copy of the grid (Grid::deepCopy()).

Example:: #include <openvdb/openvdb.h>

#include <openvdb/io/Queue.h>

#include <tbb/concurrent_hash_map.h>

#include <functional>

using openvdb::io::Queue;

struct MyNotifier

{

// Use a concurrent container, because queue callback functions

// must be thread-safe.

using FilenameMap = tbb::concurrent_hash_map<Queue::Id, std::string>;

FilenameMap filenames;

// Callback function that prints the status of a completed task.

void callback(Queue::Id id, Queue::Status status)

{

const bool ok = (status == Queue::SUCCEEDED);

FilenameMap::accessor acc;

if (filenames.find(acc, id)) {

std::cout << (ok ? "wrote " : "failed to write ")

<< acc->second << std::endl;

filenames.erase(acc);

}

}

};

int main()

{

// Construct an object to receive notifications from the queue.

// The object's lifetime must exceed the queue's.

MyNotifier notifier;

Queue queue;

// Register the callback() method of the MyNotifier object

// to receive notifications of completed tasks.

queue.addNotifier(std::bind(&MyNotifier::callback, &notifier,

std::placeholders::_1, std::placeholders::_2));

// Queue grids for output (e.g., for each step of a simulation).

for (int step = 1; step <= 10; ++step) {

openvdb::FloatGrid::Ptr grid = ...;

std::ostringstream os;

os << "mygrid." << step << ".vdb";

const std::string filename = os.str();

Queue::Id id = queue.writeGrid(grid, openvdb::io::File(filename));

// Associate the filename with the ID of the queued task.

MyNotifier::FilenameMap::accessor acc;

notifier.filenames.insert(acc, id);

acc->second = filename;

}

}

Output:
wrote mygrid.1.vdb

wrote mygrid.2.vdb

wrote mygrid.4.vdb

wrote mygrid.3.vdb

...

wrote mygrid.10.vdb

Note that tasks do not necessarily complete in the order in which they were queued.

Definition at line 100 of file Queue.h.

Member Typedef Documentation

using openvdb::OPENVDB_VERSION_NAME::io::Queue::Id = Index32

ID number of a queued task or of a registered notification callback.

Definition at line 110 of file Queue.h.

using openvdb::OPENVDB_VERSION_NAME::io::Queue::Notifier = std::function<void (Id, Status)>

Definition at line 144 of file Queue.h.

Member Enumeration Documentation

enum openvdb::OPENVDB_VERSION_NAME::io::Queue::Status

Status of a queued task.

Enumerator
UNKNOWN
PENDING
SUCCEEDED
FAILED

Definition at line 113 of file Queue.h.

Constructor & Destructor Documentation

openvdb::OPENVDB_VERSION_NAME::io::Queue::Queue ( Index32 capacity = DEFAULT_CAPACITY )

explicit

Construct a queue with the given capacity.

openvdb::OPENVDB_VERSION_NAME::io::Queue::~Queue ( )

Block until all queued tasks complete (successfully or unsuccessfully).

Member Function Documentation

Id openvdb::OPENVDB_VERSION_NAME::io::Queue::addNotifier ( Notifier )

Register a function that will be called with a task's ID and status when that task completes, whether successfully or not.

Returns: an ID that can be passed to removeNotifier() to deregister the function

When multiple notifiers are registered, they are called in the order in which they were registered.

Warning: Notifiers are called from worker threads, so they must be thread-safe and their lifetimes must exceed that of the queue. They must also not call, directly or indirectly, addNotifier(), removeNotifier() or clearNotifiers(), as that can result in a deadlock.

Index32 openvdb::OPENVDB_VERSION_NAME::io::Queue::capacity ( ) const

Return the maximum number of tasks allowed in the queue.

Once the queue has reached its maximum size, adding a new task will block until an existing task has executed.

void openvdb::OPENVDB_VERSION_NAME::io::Queue::clearNotifiers ( )

Deregister all notifiers.

bool openvdb::OPENVDB_VERSION_NAME::io::Queue::empty ( ) const

Return true if the queue is empty.

void openvdb::OPENVDB_VERSION_NAME::io::Queue::removeNotifier ( Id )

Deregister the notifier with the given ID.

void openvdb::OPENVDB_VERSION_NAME::io::Queue::setCapacity ( Index32 )

Set the maximum number of tasks allowed in the queue.

void openvdb::OPENVDB_VERSION_NAME::io::Queue::setTimeout ( Index32 seconds = DEFAULT_TIMEOUT )

Set the maximum number of seconds to wait to queue a task when the queue is full.

Index32 openvdb::OPENVDB_VERSION_NAME::io::Queue::size ( ) const

Return the number of tasks currently in the queue.

Status openvdb::OPENVDB_VERSION_NAME::io::Queue::status ( Id ) const

Return the status of the task with the given ID.

Note: Querying the status of a task that has already completed (whether successfully or not) removes the task from the status registry. Subsequent queries of its status will return UNKNOWN.

Index32 openvdb::OPENVDB_VERSION_NAME::io::Queue::timeout ( ) const

Return the maximum number of seconds to wait to queue a task when the queue is full.

template<typename GridPtrContainer >

Queue::Id openvdb::OPENVDB_VERSION_NAME::io::Queue::write	(	const GridPtrContainer &	grids,
		const Archive &	archive,
		const MetaMap &	fileMetadata = `MetaMap()`
	)

inline

Queue a container of grids for output to a file.

Parameters

grids	any iterable container of grid pointers (e.g., a GridPtrVec or GridPtrSet)
archive	the io::File or io::Stream to which to output the grids
fileMetadata	optional file-level metadata

Returns: an ID with which the status of the queued task can be queried

Exceptions

RuntimeError if the task cannot be queued within the time limit (see setTimeout()) because the queue is full

Example:: openvdb::FloatGrid::Ptr floatGrid = ...;

openvdb::BoolGrid::Ptr boolGrid = ...;

openvdb::GridPtrVec grids;

grids.push_back(floatGrid);

grids.push_back(boolGrid);

openvdb::io::Queue queue;

// Write the grids to the file mygrid.vdb.

queue.write(grids, openvdb::io::File("mygrid.vdb"));

// Stream the grids to a (binary) string.

std::ostringstream ostr(std::ios_base::binary);

queue.write(grids, openvdb::io::Stream(ostr));

Definition at line 226 of file Queue.h.

template<>

Queue::Id openvdb::OPENVDB_VERSION_NAME::io::Queue::write	(	const GridCPtrVec &	grids,
		const Archive &	archive,
		const MetaMap &	metadata
	)

inline

Definition at line 237 of file Queue.h.

Id openvdb::OPENVDB_VERSION_NAME::io::Queue::writeGrid	(	GridBase::ConstPtr	grid,
		const Archive &	archive,
		const MetaMap &	fileMetadata = `MetaMap()`
	)

Queue a single grid for output to a file or stream.

Parameters

grid	the grid to be serialized
archive	the io::File or io::Stream to which to output the grid
fileMetadata	optional file-level metadata

Returns: an ID with which the status of the queued task can be queried

Exceptions

RuntimeError if the task cannot be queued within the time limit (see setTimeout()) because the queue is full

Example:: openvdb::FloatGrid::Ptr grid = ...;

openvdb::io::Queue queue;

// Write the grid to the file mygrid.vdb.

queue.writeGrid(grid, openvdb::io::File("mygrid.vdb"));

// Stream the grid to a binary string.

std::ostringstream ostr(std::ios_base::binary);

queue.writeGrid(grid, openvdb::io::Stream(ostr));

Member Data Documentation

const Index32 openvdb::OPENVDB_VERSION_NAME::io::Queue::DEFAULT_CAPACITY = 100

static

Default maximum queue length (see setCapacity())

Definition at line 104 of file Queue.h.

const Index32 openvdb::OPENVDB_VERSION_NAME::io::Queue::DEFAULT_TIMEOUT = 120

static

Default maximum time in seconds to wait to queue a task when the queue is full (see setTimeout())

Definition at line 107 of file Queue.h.

The documentation for this class was generated from the following file:

openvdb/io/Queue.h

Public Types