#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< Bool >	BrowseAllWeakReferences (const void oldTarget, const ValueReceiver< WeakRefBase > &receiver)

Private Member Functions
	MAXON_INTERFACE_NONVIRTUAL (WeakRefServices, MAXON_REFERENCE_STATIC, "net.maxon.interface.weakrefservices", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL	(	WeakRefServices	,
		MAXON_REFERENCE_STATIC	,
		"net.maxon.interface.weakrefservices"	,
		MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")
	)

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] target Pointer 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]	weakRef	Weak reference.
[in]	target	Pointer 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] weakRef Weak reference to be destructed.

◆ MoveWeakReference()

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

static

Move constructs a weak reference.

Parameters

[in]	dst	Destination
[in]	src	Source

◆ CopyWeakReference()

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

static

Copy constructs a weak reference.

Parameters

[in]	dst	Destination
[in]	src	Source

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] target Pointer 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]	oldTarget	Pointer to old target object (must be valid).
[in]	newTarget	Pointer 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]	target	Pointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]	callback	Pointer to the callback.
[in]	callbackData	Data 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]	target	Pointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]	callback	Pointer to the callback.
[in]	callbackData	Either 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]	target	Pointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]	uniqueId	Unique pointer to an id (either an InternedId or a private static Id).
[in]	metadata	Pointer to metadata (or the metadata itself).
[in]	destruct	Optional 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]	target	Pointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]	uniqueId	Unique 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]	target	Pointer to strongly referenced target object, guaranteed to be valid and not nullptr.
[in]	uniqueId	Unique 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

Static Public Member Functions

Private Member Functions

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

◆ HasWeakReferences()

◆ AddWeakReference()

◆ RemoveWeakReference()

◆ MoveWeakReference()

◆ CopyWeakReference()

◆ ClearAllWeakReferences()

◆ TransferAllWeakReferences()

◆ AddObserver()

◆ EraseObserver()

◆ AddMetadata()

◆ EraseMetadata()

◆ GetMetadata()

◆ BrowseAllWeakReferences()