Dataset handles

Working with Safe Dataset Handles

Overview: What is mv::Dataset?

ManiVault provides a safe dataset handle class, mv::Dataset, which acts as a smart handle for dataset objects. Unlike a raw pointer or a reference-counted smart pointer, mv::Dataset is a guarded pointer to a dataset (a QObject-derived object) that automatically keeps itself up-to-date with the dataset's lifecycle. In practice, this means the handle will reset to nullptr if the underlying dataset is deleted or removed from the system, preventing dangling pointers. The class behaves much like Qt’s QPointer – “a guarded pointer” that behaves like a normal pointer except that it is automatically cleared when the referenced object is destroyed. This makes mv::Dataset ideal for storing references to datasets you don’t own, since you can safely test the pointer for validity at any time.

Key characteristics of mv::Dataset include:

• Not reference-counted: The handle does not increase the dataset’s reference count or ownership. It’s a non-owning pointer (similar to a weak pointer) that simply observes the dataset. If the dataset is destroyed elsewhere, the handle is automatically set to null, rather than keeping it alive as a shared pointer would. This avoids memory management complexities and ensures the dataset can be freed on time.
• Automatic nullification on deletion: If the dataset is removed or deleted, the handle detects this and clears its internal pointer. Any attempt to use the handle after that will safely see it as nullptr (invalid), instead of a dangerous dangling pointer.
• Pointer-like syntax: The class overloads the standard pointer operators (->, *, etc.) to allow idiomatic access to the dataset’s methods and properties.
• Integrated Qt signals: The dataset handle is also a QObject that emits Qt signals when key events occur on the dataset (renamed, removed, etc.), making it easy to integrate into plugins or applications.

---

Why Use a Safe Dataset Handle Instead of Raw Pointers?

• No Dangling Pointers: Automatically resets to null when the dataset is deleted.
• No Ownership Issues: Avoids reference-counting; the handle doesn't manage the dataset's lifetime.
• Validity Checking: You can call .isValid() or simply if (handle) to check if the dataset still exists.
• Minimal Refactoring: You can still use handle->method() or (*handle) as if it's a raw pointer.

Example:

mv::Dataset dataset = getSomeDataset();
if (!dataset.isValid()) {
    return;
}
qDebug() << "Dataset name:" << dataset->getName();

---

Lifecycle Behavior and Auto-Reset

mv::Dataset uses internal GUID tracking and event listening to determine whether the underlying dataset still exists.

When a dataset is removed:

• ManiVault emits a removal event.
• The handle resets its internal pointer and emits its own Qt signal (removed).
• isValid() will return false.

You never need to delete a dataset through this handle; the core owns it.

---

Pointer-Like Access via Operator Overloading

• operator->() lets you call dataset methods.
• operator*() gives a reference to the dataset.
• operator() returns the raw pointer.
• get<T>() lets you cast to a specific subclass.
• Copying/assigning handles shares the dataset (non-owning).

Example:

if (datasetHandle.isValid()) {
    QString name = datasetHandle->getName();
    process(*datasetHandle);
}

---

Event Rebroadcasting and Qt Signal Integration

mv::Dataset listens to core events and re-emits them as Qt signals. These include:

• guiNameChanged()
• dataChanged()
• dataDimensionsChanged()
• dataSelectionChanged()
• childAdded(const mv::Dataset&)
• childRemoved(const QString&)
• aboutToBeRemoved()
• removed(const QString&)

You can use connect() to handle these in your plugin:

connect(&datasetHandle, &mv::Dataset<>::dataChanged, this, &MyViewer::onDataChanged);

---

Conclusion

The mv::Dataset safe handle is a smart, non-owning, event-aware wrapper that simplifies how plugins and applications interact with datasets in ManiVault.

Use it whenever you hold onto a dataset for any length of time:

• It's safer than a raw pointer.
• It's more efficient than a shared pointer.
• It's Qt-native thanks to its signal rebroadcasting.

Adopt mv::Dataset as your default way of referencing datasets in ManiVault.