Describes a memory buffer on host or device, and who keeps it alive.
A descriptor for one contiguous buffer that may reside on the host or on a GPU device. It carries only primitive values – pointer as an integer, size, memory space and role – so it passes freely between C++, Python and external frameworks such as CuPy, PyTorch or Tack.
Memory spaces:
- "host" – CPU / system memory
- "cuda" – NVIDIA device memory
- "hip" – AMD device memory
- "level_zero" – Intel Level Zero device memory
There is deliberately no "metal" space. Viskores has no Metal device adapter and vtkDataArray::MemorySpace has no Metal value, so nothing in VTK could branch on one. Metal memory arrives as "host": a shared-storage MTLBuffer on Apple Silicon is unified memory, so its pointer really is a host pointer, and a private-storage buffer has no host-readable pointer at all and is rejected rather than described.
A space names what kind of memory this is, not which device or context it belongs to. There is no device ordinal here and no context handle. That is enough for host, CUDA and HIP, where a pointer identifies itself to the runtime, but not for Level Zero, whose pointers are only meaningful inside the ze_context_handle_t they were allocated from – which is why vtkmDataArrayFactory refuses "level_zero" rather than guessing.
Lifetime
A descriptor that only described memory would be unusable for anything but an immediate copy: the consumer has no way to stop the producer freeing the buffer out from under it. So a descriptor also carries how to release the producer's hold, in one of two forms:
- SetOwner() for memory owned by a VTK object. The descriptor holds a reference, so the array cannot be destroyed while the descriptor lives. This is the natural form when VTK is the producer.
- SetRelease() for memory owned by something outside VTK – a CuPy array, a Tack field, a simulation's own allocator. The callback is invoked with its context when the hold is dropped. This is the same shape as DLPack's manager_ctx + deleter, and for good reason: it is the only form that survives a language boundary.
Either way the rule is the same – while a descriptor holding a release exists, the memory is valid. A descriptor with neither describes memory whose lifetime the caller is managing some other way, which is legal but has to be a deliberate choice.
TakeRelease() hands the release duty to someone else, and is how memory gets handed to a consumer that will own it from then on – see vtkmDataArrayFactory, which transfers it into a Viskores buffer so the producer's hold is dropped when Viskores is finished with the memory.
- See also
- vtkmDataArrayFactory, vtkDataArray::NewMemoryDescriptors
- Tests:
- vtkMemoryDescriptor (Tests)
Definition at line 74 of file vtkMemoryDescriptor.h.
|
| virtual vtkTypeBool | IsA (const char *type) |
| | Return 1 if this class is the same type of (or a subclass of) the named class.
|
| vtkMemoryDescriptor * | NewInstance () const |
| void | PrintSelf (ostream &os, vtkIndent indent) override |
| | Methods invoked by print to print information about the object including superclasses.
|
| void | Set (vtkTypeInt64 pointer, vtkTypeInt64 sizeInBytes, const char *memorySpace, const char *role="data") |
| | Convenience: set the description in one call.
|
| void | SetRelease (ReleaseFunction release, void *context) |
| | Keep non-VTK memory alive by holding a release callback.
|
| void | SetReleaseAddress (vtkTypeInt64 release, vtkTypeInt64 context) |
| | As SetRelease(), taking both addresses as integers.
|
| bool | HasOwnership () const |
| | Whether this descriptor currently keeps the memory alive.
|
| bool | TakeRelease (ReleaseFunction &release, void *&context) |
| | Hand the release duty to the caller.
|
| virtual void | SetPointer (vtkTypeInt64) |
| | The memory address as a 64-bit integer.
|
| virtual vtkTypeInt64 | GetPointer () |
| | The memory address as a 64-bit integer.
|
| virtual void | SetSizeInBytes (vtkTypeInt64) |
| | Size of the buffer in bytes.
|
| virtual vtkTypeInt64 | GetSizeInBytes () |
| | Size of the buffer in bytes.
|
| virtual void | SetMemorySpace (const char *) |
| | Memory space identifier: "host", "cuda", "hip", "level_zero".
|
| virtual char * | GetMemorySpace () |
| | Memory space identifier: "host", "cuda", "hip", "level_zero".
|
| virtual void | SetRole (const char *) |
| | Role of this buffer within the array.
|
| virtual char * | GetRole () |
| | Role of this buffer within the array.
|
| void | SetOwner (vtkObject *owner) |
| | Keep a VTK object alive for as long as this descriptor lives.
|
| virtual vtkObject * | GetOwner () |
| | Keep a VTK object alive for as long as this descriptor lives.
|
| ReleaseFunction | GetRelease () const |
| | The release callback and its context, or nullptr if none is held.
|
| void * | GetReleaseContext () const |
| | The release callback and its context, or nullptr if none is held.
|
| vtkTypeInt64 | GetReleaseAddress () const |
| | The release callback and its context as integers, for wrapped callers.
|
| vtkTypeInt64 | GetReleaseContextAddress () const |
| | The release callback and its context as integers, for wrapped callers.
|
| | vtkBaseTypeMacro (vtkObject, vtkObjectBase) |
| virtual void | DebugOn () |
| | Turn debugging output on.
|
| virtual void | DebugOff () |
| | Turn debugging output off.
|
| bool | GetDebug () |
| | Get the value of the debug flag.
|
| void | SetDebug (bool debugFlag) |
| | Set the value of the debug flag.
|
| virtual void | Modified () |
| | Update the modification time for this object.
|
| virtual vtkMTimeType | GetMTime () |
| | Return this object's modified time.
|
| void | PrintSelf (ostream &os, vtkIndent indent) override |
| | Methods invoked by print to print information about the object including superclasses.
|
| void | RemoveObserver (unsigned long tag) |
| void | RemoveObservers (unsigned long event) |
| void | RemoveObservers (const char *event) |
| void | RemoveAllObservers () |
| vtkTypeBool | HasObserver (unsigned long event) |
| vtkTypeBool | HasObserver (const char *event) |
| vtkTypeBool | InvokeEvent (unsigned long event) |
| vtkTypeBool | InvokeEvent (const char *event) |
| std::string | GetObjectDescription () const override |
| | The object description printed in messages and PrintSelf output.
|
| unsigned long | AddObserver (unsigned long event, vtkCommand *, float priority=0.0f) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| unsigned long | AddObserver (const char *event, vtkCommand *, float priority=0.0f) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| vtkCommand * | GetCommand (unsigned long tag) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| void | RemoveObserver (vtkCommand *) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| void | RemoveObservers (unsigned long event, vtkCommand *) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| void | RemoveObservers (const char *event, vtkCommand *) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| vtkTypeBool | HasObserver (unsigned long event, vtkCommand *) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| vtkTypeBool | HasObserver (const char *event, vtkCommand *) |
| | Allow people to add/remove/invoke observers (callbacks) to any VTK object.
|
| template<class U, class T> |
| unsigned long | AddObserver (unsigned long event, U observer, void(T::*callback)(), float priority=0.0f) |
| | Overloads to AddObserver that allow developers to add class member functions as callbacks for events.
|
| template<class U, class T> |
| unsigned long | AddObserver (unsigned long event, U observer, void(T::*callback)(vtkObject *, unsigned long, void *), float priority=0.0f) |
| | Overloads to AddObserver that allow developers to add class member functions as callbacks for events.
|
| template<class U, class T> |
| unsigned long | AddObserver (unsigned long event, U observer, bool(T::*callback)(vtkObject *, unsigned long, void *), float priority=0.0f) |
| | Allow user to set the AbortFlagOn() with the return value of the callback method.
|
| vtkTypeBool | InvokeEvent (unsigned long event, void *callData) |
| | This method invokes an event and return whether the event was aborted or not.
|
| vtkTypeBool | InvokeEvent (const char *event, void *callData) |
| | This method invokes an event and return whether the event was aborted or not.
|
| virtual void | SetObjectName (const std::string &objectName) |
| | Set/get the name of this object for reporting purposes.
|
| virtual std::string | GetObjectName () const |
| | Set/get the name of this object for reporting purposes.
|
| const char * | GetClassName () const |
| | Return the class name as a string.
|
| virtual vtkIdType | GetNumberOfGenerationsFromBase (const char *name) |
| | Given the name of a base class of this class type, return the distance of inheritance between this class type and the named class (how many generations of inheritance are there between this class and the named class).
|
| virtual void | Delete () |
| | Delete a VTK object.
|
| virtual void | FastDelete () |
| | Delete a reference to this object.
|
| void | InitializeObjectBase () |
| void | Print (ostream &os) |
| | Print an object to an ostream.
|
| void | Register (vtkObjectBase *o) |
| | Increase the reference count (mark as used by another object).
|
| virtual void | UnRegister (vtkObjectBase *o) |
| | Decrease the reference count (release by another object).
|
| int | GetReferenceCount () |
| | Return the current reference count of this object.
|
| void | SetReferenceCount (int) |
| | Sets the reference count.
|
| bool | GetIsInMemkind () const |
| | A local state flag that remembers whether this object lives in the normal or extended memory space.
|
| virtual void | PrintHeader (ostream &os, vtkIndent indent) |
| | Methods invoked by print to print information about the object including superclasses.
|
| virtual void | PrintTrailer (ostream &os, vtkIndent indent) |
| | Methods invoked by print to print information about the object including superclasses.
|
| virtual bool | UsesGarbageCollector () const |
| | Indicate whether the class uses vtkGarbageCollector or not.
|
|
| static vtkMemoryDescriptor * | New () |
| static vtkTypeBool | IsTypeOf (const char *type) |
| static vtkMemoryDescriptor * | SafeDownCast (vtkObjectBase *o) |
| static vtkObject * | New () |
| | Create an object with Debug turned off, modified time initialized to zero, and reference counting on.
|
| static void | BreakOnError () |
| | This method is called when vtkErrorMacro executes.
|
| static void | SetGlobalWarningDisplay (vtkTypeBool val) |
| | This is a global flag that controls whether any debug, warning or error messages are displayed.
|
| static void | GlobalWarningDisplayOn () |
| | This is a global flag that controls whether any debug, warning or error messages are displayed.
|
| static void | GlobalWarningDisplayOff () |
| | This is a global flag that controls whether any debug, warning or error messages are displayed.
|
| static vtkTypeBool | GetGlobalWarningDisplay () |
| | This is a global flag that controls whether any debug, warning or error messages are displayed.
|
| static vtkTypeBool | IsTypeOf (const char *name) |
| | Return 1 if this class type is the same type of (or a subclass of) the named class.
|
| static vtkIdType | GetNumberOfGenerationsFromBaseType (const char *name) |
| | Given a the name of a base class of this class type, return the distance of inheritance between this class type and the named class (how many generations of inheritance are there between this class and the named class).
|
| static vtkObjectBase * | New () |
| | Create an object with Debug turned off, modified time initialized to zero, and reference counting on.
|
| static void | SetMemkindDirectory (const char *directoryname) |
| | The name of a directory, ideally mounted -o dax, to memory map an extended memory space within.
|
| static bool | GetUsingMemkind () |
| | A global state flag that controls whether vtkObjects are constructed in the usual way (the default) or within the extended memory space.
|
1.16.1