Eternal< T >

#include <Ultralight/js/Holder.h>

Overview

template<typename T>
class ultralight::js::Eternal< T >

Non-owning holder for bound-class singletons and program-lifetime objects.

An Eternal wraps a pointer to a native object that lives for the entire run of the application and is never destroyed, such as an engine subsystem or a global singleton. It lets page scripts interact with the native instance through a standard JavaScript wrapper without reference counting or ownership transfers.

You'll typically specialize js::ClassHolder with Eternal beside the class declaration so every file that binds or converts the class includes it. This makes Eternal the class's canonical holder, allowing you to assign the singleton directly to an API path.

This example exposes a game's world singleton to the page as app.world:

class GameWorld {
 public:
  static GameWorld& Current();
};
 
template <>
struct ultralight::js::ClassHolder<GameWorld> {
  using type = js::Eternal<GameWorld>;
};
 
void RegisterWorld(js::API& api) {
  api.DefineClass<GameWorld>("GameWorld");  // no Constructor: `new` throws
  api["world"] = js::Eternal(&GameWorld::Current());
}

Differences from Raw Pointers

Both a T* and an Eternal leave ownership with you, but they differ in how they can cross the bridge:

• Raw pointers cannot be assigned to an API path directly. A bound function or property getter can return a T* to give the page a wrapper that lasts, but raw pointers can't be passed to API::Emit() or Resolver::Resolve().
• Eternal holders support direct assignment and deferred deliveries. An Eternal can be assigned directly to an API path (as shown above) or passed to API::Emit() and Resolver::Resolve(), which deliver the instance on a later frame during Renderer::Update().

Note

ClassBuilder::Constructor() doesn't support classes whose canonical holder is an Eternal. Calling new on the page throws a TypeError with code ULJS_NO_CTOR (use a property binding or a static method returning the Eternal instead).

See also

js::ClassHolder, js::ClassBuilder, ultralight::HolderTraits

Public Member Functions
constexpr	Eternal ()=default
	Create an empty Eternal.
constexpr	Eternal (T *instance)
	Create an Eternal for an instance.
T *	get () const
	Get the instance (NULL when empty).
	operator bool () const
	Whether or not this holds an instance.

Constructor & Destructor Documentation

Eternal() [1/2]

template<typename T>

Eternal ( )

constexprdefault

Create an empty Eternal.

Eternal() [2/2]

template<typename T>

Eternal ( T * instance )

inlineexplicitconstexpr

Create an Eternal for an instance.

Parameters

instance

The instance, which must never be destroyed.

Member Function Documentation

get()

template<typename T>

T * get ( ) const

inline

Get the instance (NULL when empty).

operator bool()

template<typename T>

operator bool ( ) const

inlineexplicit

Whether or not this holds an instance.

---

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

• Ultralight/js/Holder.h