WeakRawPointer Handbook

Cinema 4D S24 API brings WeakRawPtr defined in weakrawptr.h.

maxon::StrongRef and maxon::WeakRef are useful tools when a Maxon data types comes into play.

A maxon::StrongRef is a smart pointer that is used to implement shared ownership over an object. The pointed object is kept alive until the last maxon::StrongRef is set to nullptr.

  // strongVectorA and strongVectorB share the ownership of the referenced vector.
  maxon::StrongRef<maxon::Vector> strongVectorA = NewObj(maxon::Vector, maxon::Vector(100.0_f, 0.0_f, 0.0_f)) iferr_return;
  maxon::StrongRef<maxon::Vector> strongVectorB = strongVectorA;
    
  strongVectorA = nullptr;
  
  // vectorAIsStillAlive is true, as strongVectorB kept the object alive.
  Bool vectorAIsStillAlive = strongVectorB.GetPointer() != nullptr;

A maxon::WeakRef is a smart pointer which does not have ownership the referenced object. Once the referenced object is set to a nullptr, the the maxon::WeakRef will return nullptr.

  // weakVector does not own the referenced vector, but strongVector does.
  maxon::StrongRef<maxon::Vector> strongVector = NewObj(maxon::Vector, maxon::Vector(100.0_f, 0.0_f, 0.0_f)) iferr_return;
  maxon::WeakRef<maxon::StrongRef<maxon::Vector>> weakVector = strongVector;
    
  strongVector = nullptr;
    
  maxon::StrongRef<maxon::Vector> checkRef = weakVector;
  // vectorIsStillAlive will be false.
  Bool vectorIsStillAlive = checkRef.GetPointer() != nullptr;

These tools are designed to work together. A maxon::WeakRef can reference only objects owned by a maxon::StrongRef.

But what about unmanaged memory, like raw pointers?

We can use WeakRef concept for any kind of memory, which has been allocated using NewMem() or NewObj(), by using the maxon::WeakRawPtr template.
Since every memory allocation done in that way is reference counted.

To use maxon::WeakRawPtr, include the weakrawptr.h file and assign the pointer of the newly object to a maxon::WeakRawPtr:

  #include "maxon/weakrawptr.h"
 
  maxon::Vector* rawPtr = NewObj(maxon::Vector, maxon::Vector(100.0_f, 0.0_f, 0.0_f)) iferr_return;
  maxon::WeakRawPtr<maxon::Vector> safePtr;
  // Assign the raw pointer
  safePtr.Set(rawPtr);
    
  // This is fine, the pointer is still valid.
  maxon::Vector* checkPtr = safePtr.Get();
    
  // Somewhere else in the code
  DeleteObj(rawPtr);
  
  // checkPtr2 will return the nullptr, as safePtr knows that the original memory has been 
  // deallocated.
  maxon::Vector* checkPtr2 = safePtr.Get();

This can be applied to safely handle pointers to legacy Cinema 4D objects, like BaseObject or BaseDocument.

Note

It is safe as long as the memory or object is not released in a different thread. For these rare cases the maxon::WeakRefBase needs to be locked. Access the memory is then only allowed until the maxon::WeakRefBase is unlocked again.

maxon::WeakRawPtr can be used similarly to a BaseLink, without the huge dependency on BaseDocument that BaseLink has.

  BaseObject* cube = BaseObject::Alloc(Ocube);
  if (cube == nullptr)
  {
    return maxon::IllegalStateError(MAXON_SOURCE_LOCATION);
  }
    
  maxon::WeakRawPtr<BaseObject> safeCube;
  safeCube.Set(cube);
    
  MAXON_SCOPE
  {
    // checkCubePtr is valid, we can use it.
    BaseObject* checkCubePtr = safeCube.Get();
        
    // Delete the cube
    BaseObject::Free(checkCubePtr);
  }
    
  // cube is not alive anymore, and checkCubePtr is dangling. safeCube.Get() we can correctly set
  // checkCubePtr2 to the nullptr.
  BaseObject* checkCubePtr2 = safeCube.Get();

This is helpful when a legacy object pointer or a raw memory needs to be passed to a lambda, Delegate or an observable capture.
Since the pointed object's validity can be checked regardless of the time.