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

#include <openvdb/io/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.

Member Typedef Documentation

using Id = Index32

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

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

Member Enumeration Documentation

enum Status

Status of a queued task.

Enumerator
UNKNOWN
PENDING
SUCCEEDED
FAILED

Constructor & Destructor Documentation

Queue ( Index32 capacity = DEFAULT_CAPACITY )

explicit

Construct a queue with the given capacity.

~Queue ( )

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

Member Function Documentation

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.

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 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 clearNotifiers ( )

Deregister all notifiers.

bool empty ( ) const

Return true if the queue is empty.

void removeNotifier ( Id )

Deregister the notifier with the given ID.

void setCapacity ( Index32 )

Set the maximum number of tasks allowed in the queue.

void setTimeout ( Index32 seconds = DEFAULT_TIMEOUT )

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

Index32 size ( ) const

Return the number of tasks currently in the queue.

Status 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 timeout ( ) const

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

Queue::Id 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));

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

inline

Id 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 DEFAULT_CAPACITY = 100

static

Default maximum queue length (see setCapacity())

const Index32 DEFAULT_TIMEOUT = 120

static

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

Public Types