WeakRefServices Class Reference

#include <weakrefservices.h>

Static Public Member Functions

static MAXON_METHOD Bool HasWeakReferences (const void *target)
 
static MAXON_METHOD Bool AddWeakReference (WeakRefBase &weakRef, const void *target)
 
static MAXON_METHOD void RemoveWeakReference (WeakRefBase &weakRef)
 
static MAXON_METHOD void MoveWeakReference (WeakRefBase &dst, WeakRefBase &src)
 
static MAXON_METHOD Bool CopyWeakReference (WeakRefBase &dst, const WeakRefBase &src)
 
static MAXON_WARN_UNUSED MAXON_METHOD Bool ClearAllWeakReferences (const void *target)
 
static MAXON_METHOD Bool TransferAllWeakReferences (const void *oldTarget, const void *newTarget)
 
static MAXON_METHOD Bool AddObserver (const void *target, MemoryObserverCallback callback, void *callbackData)
 
static MAXON_METHOD Bool EraseObserver (const void *target, MemoryObserverCallback callback, void *callbackData)
 
static MAXON_METHOD Bool AddMetadata (const void *target, const Id *uniqueId, void *metadata, MemoryMetadataDestructor destruct=nullptr)
 
static MAXON_METHOD Bool EraseMetadata (const void *target, const Id *uniqueId)
 
static MAXON_METHOD MemoryMetadataProxy GetMetadata (const void *target, const Id *uniqueId)
 
static MAXON_METHOD Result< BoolBrowseAllWeakReferences (const void *oldTarget, const ValueReceiver< WeakRefBase * > &receiver)
 

Private Member Functions

 MAXON_INTERFACE_NONVIRTUAL (WeakRefServices, MAXON_REFERENCE_NONE, "net.maxon.interface.weakrefservices")
 

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( WeakRefServices  ,
MAXON_REFERENCE_NONE  ,
"net.maxon.interface.weakrefservices"   
)
private

◆ HasWeakReferences()

static MAXON_METHOD Bool HasWeakReferences ( const void *  target)
static

Returns true if there currently are weak references to the target. This does not take other metadata into account, just the weak references.

Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
Returns
True if there are weak references to the target.

◆ AddWeakReference()

static MAXON_METHOD Bool AddWeakReference ( WeakRefBase weakRef,
const void *  target 
)
static

Adds a weak reference to a strongly referenced object.

Note
The caller must hold a strong reference to the target object.
Parameters
[in]weakRefWeak reference.
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
Returns
True on success, false if reference could not be created (due to out of memory).

◆ RemoveWeakReference()

static MAXON_METHOD void RemoveWeakReference ( WeakRefBase weakRef)
static

Removes a weak reference.

Parameters
[in]weakRefWeak reference to be destructed.

◆ MoveWeakReference()

static MAXON_METHOD void MoveWeakReference ( WeakRefBase dst,
WeakRefBase src 
)
static

Move constructs a weak reference.

Parameters
[in]dstDestination
[in]srcSource

◆ CopyWeakReference()

static MAXON_METHOD Bool CopyWeakReference ( WeakRefBase dst,
const WeakRefBase src 
)
static

Copy constructs a weak reference.

Parameters
[in]dstDestination
[in]srcSource
Returns
True on success, false if copying failed (due to out of memory).

◆ ClearAllWeakReferences()

static MAXON_WARN_UNUSED MAXON_METHOD Bool ClearAllWeakReferences ( const void *  target)
static

Removes all weak references to a strongly referenced object (usually called when it is going to be destructed).

Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be not nullptr.
Returns
True if the target can be destructed, false if the ownership has been transferred and the target must not be destructed.

◆ TransferAllWeakReferences()

static MAXON_METHOD Bool TransferAllWeakReferences ( const void *  oldTarget,
const void *  newTarget 
)
static

All weak references to oldTarget will be updated and point to newTarget. The caller holds a strong reference to the old target. After the call there'll be no more weak references pointing to the old target (until new ones are created).

Parameters
[in]oldTargetPointer to old target object (must be valid).
[in]newTargetPointer to new target object (might be nullptr).
Returns
True on success, false if copying failed (due to out of memory).

◆ AddObserver()

static MAXON_METHOD Bool AddObserver ( const void *  target,
MemoryObserverCallback  callback,
void *  callbackData 
)
static

Adds an observer which will be invoked before a strongly referenced object is destructed. The observer can claim (shared) ownership of the target by returning CLAIM_OWNERSHIP. In this case it should add a reference to it and destruct it at a later point in time. While the observer is called the internal metadata structure of the target is locked. You can request to be invoked after the target has been unlocked.

Note
You must not create or delete weak references or metadata which refer to the target inside the observer when the target is locked!
Since the observer is also performance critical it should be as short as possible and should only call code with known implications.
Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]callbackPointer to the callback.
[in]callbackDataData private to the callback.
Returns
True on success, false if reference could not be created (due to out of memory).

◆ EraseObserver()

static MAXON_METHOD Bool EraseObserver ( const void *  target,
MemoryObserverCallback  callback,
void *  callbackData 
)
static

Erases an observer which was installed with AddObserver. This is only required if the observer or its data becomes invalid or is to be released before the target object has been released.

Note
You must not call this method from inside the observer callback when the target is locked!
The callbackData is not erased, it's required to match the value used for AddObserver.
Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]callbackPointer to the callback.
[in]callbackDataEither nullptr (just the callback pointer is relevant) or it must match the call to AddObserver.
Returns
True on success, false if the observer couldn't be removed (target does not exist anymore or callback/callbackData does not match).

◆ AddMetadata()

static MAXON_METHOD Bool AddMetadata ( const void *  target,
const Id uniqueId,
void *  metadata,
MemoryMetadataDestructor  destruct = nullptr 
)
static

Adds metadata to a target object.

Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]uniqueIdUnique pointer to an id (either an InternedId or a private static Id).
[in]metadataPointer to metadata (or the metadata itself).
[in]destructOptional destructor for the metadata (to be called when the referenced object is destructed).
Returns
True on success, false if metadata could not be added (due to out of memory).

◆ EraseMetadata()

static MAXON_METHOD Bool EraseMetadata ( const void *  target,
const Id uniqueId 
)
static

Removes metadata from a target object.

Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]uniqueIdUnique pointer to an id (either an InternedId or a private static Id).
Returns
True on success, false if no metadata existed.

◆ GetMetadata()

static MAXON_METHOD MemoryMetadataProxy GetMetadata ( const void *  target,
const Id uniqueId 
)
static

Returns a proxy object which allows safe access to the metadata.

Parameters
[in]targetPointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]uniqueIdUnique pointer to an id (either an InternedId or a private static Id).
Returns
Proxy object for metadata.

◆ BrowseAllWeakReferences()

static MAXON_METHOD Result<Bool> BrowseAllWeakReferences ( const void *  oldTarget,
const ValueReceiver< WeakRefBase * > &  receiver 
)
static