OpenVDB: Queue Class Reference

OpenVDB 4.0.2

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 <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

## ◆ Id

using Id = Index32

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

## ◆ Notifier

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

## Member Enumeration Documentation

## ◆ Status

enum Status

Status of a queued task.

Enumerator
UNKNOWN |
PENDING |
SUCCEEDED |
FAILED |

## Constructor & Destructor Documentation

## ◆ Queue()

Queue | ( | Index32 | capacity = `DEFAULT_CAPACITY` | ) |
| explicit

Construct a queue with the given capacity.

## ◆ ~Queue()

~Queue | ( |  | ) |

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

## Member Function Documentation

## ◆ addNotifier()

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.

## ◆ capacity()

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.

## ◆ clearNotifiers()

void clearNotifiers | ( |  | ) |

Deregister all notifiers.

## ◆ empty()

bool empty | ( |  | ) | const

Return `true` if the queue is empty.

## ◆ removeNotifier()

void removeNotifier | ( | Id |  | ) |

Deregister the notifier with the given ID.

## ◆ setCapacity()

void setCapacity | ( | Index32 |  | ) |

Set the maximum number of tasks allowed in the queue.

## ◆ setTimeout()

void setTimeout | ( | Index32 | seconds = `DEFAULT_TIMEOUT` | ) |

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

## ◆ size()

Index32 size | ( |  | ) | const

Return the number of tasks currently in the queue.

## ◆ status()

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.

## ◆ timeout()

Index32 timeout | ( |  | ) | const

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

## ◆ write() [1/2]

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));

## ◆ write() [2/2]

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

## ◆ writeGrid()

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

## ◆ DEFAULT_CAPACITY

const Index32 DEFAULT_CAPACITY = 100
| static

Default maximum queue length (see setCapacity())

## ◆ DEFAULT_TIMEOUT

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:

- Queue.h