OpenVDB  5.2.0
Public Types | Public Member Functions | Static Public Attributes | List of all members
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) {
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
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));
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
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::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())


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