HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
openvdb::OPENVDB_VERSION_NAME::io::Queue Class Reference

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 <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 127 of file Queue.h.

Member Typedef Documentation

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

Definition at line 137 of file Queue.h.

Definition at line 171 of file Queue.h.

Member Enumeration Documentation

Status of a queued task.

Enumerator
UNKNOWN 
PENDING 
SUCCEEDED 
FAILED 

Definition at line 140 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
gridsany iterable container of grid pointers (e.g., a GridPtrVec or GridPtrSet)
archivethe io::File or io::Stream to which to output the grids
fileMetadataoptional file-level metadata
Returns
an ID with which the status of the queued task can be queried
Exceptions
RuntimeErrorif 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 = ...;
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 253 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 264 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
gridthe grid to be serialized
archivethe io::File or io::Stream to which to output the grid
fileMetadataoptional file-level metadata
Returns
an ID with which the status of the queued task can be queried
Exceptions
RuntimeErrorif 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 131 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 134 of file Queue.h.


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