WeakValue

#include <Ultralight/js/WeakValue.h>

Overview

A weak reference to a JavaScript object.

Unlike a js::Value, a WeakValue doesn't keep its object alive, so the garbage collector can reclaim the object. Lock() gives you a Value for the object, or an empty Value once the object is collected or its page is gone:

js::WeakValue cached(heavy_object);
// later:
if (js::Value strong = cached.Lock())
  UseCached(strong);
else
  RebuildCache();

Use a WeakValue for objects the page keeps alive by itself (eg, a cached page object or a bound instance's own JavaScript object).

Note

WeakValue is move-only. For the thread rule, see the ultralight::js namespace overview (<Ultralight/JS.h>).

Warning

Don't use a WeakValue as the only reference to a callback. If nothing in the page holds the callback, it's collected and disappears. See "Ownership Cycles" in <Ultralight/js/Class.h> for how to break a reference cycle instead.

Static Public Member Functions
static WeakValue	Adopt (ULJSWeakRef handle)
	Take ownership of a handle from the C API.

Public Member Functions
	WeakValue ()=default
	Create an empty WeakValue (Lock() returns an empty Value).
	WeakValue (const Value &target)
	Create a weak reference to target.
	~WeakValue ()
	Destructor (releases the weak reference).
	WeakValue (WeakValue &&other) noexcept
	Move constructor (other becomes empty).
WeakValue &	operator= (WeakValue &&other) noexcept
	Move assignment (releases the current weak reference first).
	WeakValue (const WeakValue &)=delete
WeakValue &	operator= (const WeakValue &)=delete
Value	Lock () const
	Get a Value for the object.
template<typename F>
void	OnCollected (F &&on_collected)
	Set a callback to run after the object is garbage collected.
bool	IsEmpty () const
	Whether or not this WeakValue holds nothing (it was default-constructed, moved from, released with LeakRef(), or created from something that isn't an object in a living page).
ULJSWeakRef	raw () const
	Get the C API handle without transferring ownership.
ULJSWeakRef	LeakRef ()
	Give up ownership of the C API handle and return it.

Constructor & Destructor Documentation

WeakValue() [1/4]

WeakValue ( )

default

Create an empty WeakValue (Lock() returns an empty Value).

WeakValue() [2/4]

WeakValue ( const Value & target )

inlineexplicit

Create a weak reference to target.

Parameters

target

The object to observe. Anything else (a primitive, an empty Value, or a Value whose page is gone) gives an empty WeakValue.

~WeakValue()

~WeakValue ( )

inline

Destructor (releases the weak reference).

WeakValue() [3/4]

WeakValue ( WeakValue && other )

inlinenoexcept

Move constructor (other becomes empty).

WeakValue() [4/4]

WeakValue ( const WeakValue & )

delete

Member Function Documentation

Adopt()

WeakValue Adopt ( ULJSWeakRef handle )

inlinestatic

Take ownership of a handle from the C API.

Parameters

handle

The handle to take ownership of.

Returns

Returns a WeakValue that owns handle.

IsEmpty()

bool IsEmpty ( ) const

inline

Whether or not this WeakValue holds nothing (it was default-constructed, moved from, released with LeakRef(), or created from something that isn't an object in a living page).

This doesn't tell you whether the object still exists. Use Lock() for that.

LeakRef()

ULJSWeakRef LeakRef ( )

inline

Give up ownership of the C API handle and return it.

Returns

Returns the handle. You must destroy it with ulDestroyJSWeakRef() when finished.

Lock()

Value Lock ( ) const

inlinenodiscard

Get a Value for the object.

Returns

Returns a valid Value for the object (an empty Value if the object was collected, its page is gone, or this WeakValue is empty).

OnCollected()

template<typename F>

void OnCollected ( F && on_collected )

inline

Set a callback to run after the object is garbage collected.

The callback runs once on the Renderer's thread during a later Renderer::Update(). Setting a new callback replaces the previous one. You can destroy this WeakValue from inside the callback.

Parameters

on_collected

A callable that takes a js::Context& or nothing.

Note

The callback never runs if the object's page goes away first or this WeakValue is destroyed first. On an empty WeakValue this does nothing.

operator=() [1/2]

WeakValue & operator= ( const WeakValue & )

delete

operator=() [2/2]

WeakValue & operator= ( WeakValue && other )

inlinenoexcept

Move assignment (releases the current weak reference first).

raw()

ULJSWeakRef raw ( ) const

inline

Get the C API handle without transferring ownership.

Returns

Returns the handle for use with the <Ultralight/CAPI/CAPI_JSRuntime.h> functions.

---

The documentation for this class was generated from the following file:

• Ultralight/js/WeakValue.h