Resolver

#include <Ultralight/js/Resolver.h>

Overview

A handle that settles a JavaScript Promise.

A Resolver lets native code settle a JavaScript Promise from any thread. Taking a Resolver as the trailing parameter of a bound function turns it into an asynchronous call that returns a Promise to the page immediately.

Pass the resolver to a background thread and settle it when the work finishes:

app["save"] = [](std::string path, js::Resolver done) {
  RunOnSaveThread([path, done = std::move(done)] {
    if (WriteSave(path))
      done.Resolve(true);
    else
      done.Reject(js::Error::Make(js::ErrorType::Error, "disk full"));
  });
};

Page script awaits the returned Promise normally:

const saved = await app.save("slot1.dat");

Settling the Promise

Resolvers follow these rules:

• Resolve() and Reject() are safe from any thread.
• Values convert on the Renderer's thread during a later Renderer::Update(). Passing an argument to Resolve() copies or moves the C++ value immediately.
• Only the first call to Resolve() or Reject() takes effect.
• Destroying an unsettled Resolver rejects the Promise. This ensures the page never waits forever.

Sharing a Resolver

Resolver is move-only and can't be captured directly by copyable types such as std::function. Wrap the resolver in std::shared_ptr to pass it into a copyable callback or job queue:

auto shared = std::make_shared<js::Resolver>(std::move(done));
jobs.push_back([shared] { shared->Resolve(42); });

Promises Outside Bound Functions

Call js::Context::MakePromise() on the page's context to create a pending Promise directly without a bound function:

auto [promise, resolver] = ctx.MakePromise();
ctx["ready"] = promise;
 
// Later, from any thread:
resolver.Resolve(std::string("ok"));

Note

If the page navigates away or closes before the Promise settles, calling Resolve() or Reject() is safe and the library discards the result.

Note

Use a Resolver when an outside system or background thread signals completion of an operation. For sequential multi-step async operations, use js::Task instead.

See also

js::Task, js::Context::MakePromise(), js::Error

Static Public Member Functions
static Resolver	Adopt (ULJSPromiseResolver handle)
	Take ownership of a resolver handle from the C API.

Public Member Functions
	Resolver ()=default
	Create an empty Resolver (Resolve() and Reject() do nothing).
	Resolver (Resolver &&other) noexcept
	Move constructor (other becomes empty).
Resolver &	operator= (Resolver &&other) noexcept
	Move assignment (other becomes empty).
	Resolver (const Resolver &)=delete
Resolver &	operator= (const Resolver &)=delete
	~Resolver ()
	Destructor (rejects the Promise if it hasn't been settled).
	operator bool () const
	Whether or not this Resolver holds a Promise (it stays true after Resolve() or Reject()).
void	Resolve () const
	Resolve the Promise with undefined.
template<typename T> requires Marshalable<detail::CapturedArg<T>>
void	Resolve (T &&value) const
	Resolve the Promise with a value.
void	Reject (Error error) const
	Reject the Promise with an error.
ULJSPromiseResolver	raw () const
	Get the C API handle without transferring ownership (this Resolver still destroys it).
ULJSPromiseResolver	LeakRef ()
	Give up ownership of the C API handle and return it.

Constructor & Destructor Documentation

Resolver() [1/3]

Resolver ( )

default

Create an empty Resolver (Resolve() and Reject() do nothing).

Resolver() [2/3]

Resolver ( Resolver && other )

inlinenoexcept

Move constructor (other becomes empty).

Resolver() [3/3]

Resolver ( const Resolver & )

delete

~Resolver()

~Resolver ( )

inline

Destructor (rejects the Promise if it hasn't been settled).

Member Function Documentation

Adopt()

Resolver Adopt ( ULJSPromiseResolver handle )

inlinestatic

Take ownership of a resolver handle from the C API.

You only need this at the C boundary (eg, for the handle a ULJSAsyncFunctionCallback receives, or to call Task::Start()). A bound function that takes a js::Resolver gets one ready to use.

Parameters

handle

The handle to take ownership of.

Returns

Returns a Resolver that owns handle.

Note

There's no FromBorrowed(): a Resolver settles its Promise once. To share one, see the class notes.

LeakRef()

ULJSPromiseResolver LeakRef ( )

inline

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

Returns

Returns the handle (this Resolver becomes empty). You must call ulDestroyJSPromiseResolver() when finished.

Warning

Destroying the handle must be its last use (see ulDestroyJSPromiseResolver()).

operator bool()

operator bool ( ) const

inlineexplicit

Whether or not this Resolver holds a Promise (it stays true after Resolve() or Reject()).

operator=() [1/2]

Resolver & operator= ( const Resolver & )

delete

operator=() [2/2]

Resolver & operator= ( Resolver && other )

inlinenoexcept

Move assignment (other becomes empty).

If this Resolver held a Promise it hasn't settled, that Promise is rejected now.

raw()

ULJSPromiseResolver raw ( ) const

inline

Get the C API handle without transferring ownership (this Resolver still destroys it).

Returns

Returns the handle (NULL if this Resolver is empty).

Warning

Destroying the handle must be its last use. If another thread settles the Promise through this handle, make sure that happens before this Resolver is destroyed.

Reject()

void Reject ( Error error ) const

inline

Reject the Promise with an error.

Parameters

error

The rejection reason.

Note

Safe to call from any thread.

Resolve() [1/2]

void Resolve ( ) const

inline

Resolve the Promise with undefined.

Note

Safe to call from any thread.

Resolve() [2/2]

template<typename T>
requires Marshalable<detail::CapturedArg<T>>

void Resolve ( T && value ) const

inline

Resolve the Promise with a value.

Parameters

value

The value, copied or moved now and converted through js::TypeTraits later on the Renderer's thread. A string literal or char* is copied into a std::string.

Note

Safe to call from any thread.

---

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

• Ultralight/js/Resolver.h