CefV8Value

Header: cef_v8.h
Sections: CefV8Context, CefV8Handler, CefV8Accessor, CefV8Interceptor, CefV8Exception, CefV8ArrayBufferReleaseCallback (+1 more)
Category: V8 & Process Messaging

Overview

JavaScript bridge, value tree, inter-process messages, shared memory regions.

Free Function: CefRegisterExtension

Source File: include/cef_v8.h

Process / Thread Context: Renderer process / renderer main thread (TID_RENDERER).

Purpose: Registers a JavaScript extension (a string of JS source containing native function prototypes) that, when called from JS, dispatches into a user-supplied CefV8Handler::Execute(). Must be called once during render-process setup (typically from CefRenderProcessHandler::OnWebKitInitialized).

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Usage Example

bool CefRegisterExtension(const CefString& extension_name,
                          const CefString& javascript_code,
                          CefRefPtr<CefV8Handler> handler);

// Inside CefRenderProcessHandler::OnWebKitInitialized():
const char* kExtJs = R"JS(
  if (!example) example = {};
  example.test = {};
  (function() {
    example.test.myFunction = function() {
      native function MyFunction();
      return MyFunction();
    };
    example.test.__defineGetter__('myparam', function() {
      native function GetMyParam();
      return GetMyParam();
    });
    example.test.__defineSetter__('myparam', function(b) {
      native function SetMyParam();
      if (b) SetMyParam(b);
    });
  })();
)JS";

class MyV8Handler : public CefV8Handler {
  bool Execute(const CefString& name,
               CefRefPtr<CefV8Value> object,
               const CefV8ValueList& arguments,
               CefRefPtr<CefV8Value>& retval,
               CefString& exception) override {
    if (name == "MyFunction") {
      retval = CefV8Value::CreateString("hello from C++");
      return true;
    }
    if (name == "GetMyParam") { retval = CefV8Value::CreateInt(myparam_); return true; }
    if (name == "SetMyParam" && !arguments.empty() && arguments[0]->IsInt()) {
      myparam_ = arguments[0]->GetIntValue();
      return true;
    }
    return false;  // not handled
  }
  int myparam_ = 0;
  IMPLEMENT_REFCOUNTING(MyV8Handler);
};

CefRegisterExtension("v8/example", kExtJs, new MyV8Handler);
// From page JS: example.test.myFunction();  example.test.myparam = 42;

CefV8Context

Source File: include/cef_v8.h

Process / Thread Context: Renderer process / TID_RENDERER or WebWorker thread (handle is single-thread-affine).

Purpose: Represents a V8 execution context (one per frame). Use Enter() / Exit() to make a stored context "current" so that CefV8Value objects belonging to that context can be created/manipulated from outside a callback.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

static CefRefPtr<CefV8Context> GetCurrentContext()

Return Value: top of V8 context stack. Renderer thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Context> GetEnteredContext()

Return Value: bottom of V8 context stack. Renderer thread.

Threading Constraint: Threading constraint not specified in source.

static bool InContext()

Return Value: true if V8 is currently inside any context. Renderer thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefTaskRunner> GetTaskRunner()

Parameters:

• (none)

Return Value: Task runner for the thread that owns this context (lets you hop back from any render-process thread).

Threading Constraint: May be called on any render-process thread.

virtual bool IsValid()

Return Value: true if handle valid and accessible on current thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefBrowser> GetBrowser()

Return Value: owning browser; empty for WebWorkers.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefFrame> GetFrame()

Return Value: owning frame; empty for WebWorkers.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8Value> GetGlobal()

Return Value: JS globalThis for this context. Context must be entered first.

Threading Constraint: Threading constraint not specified in source.

virtual bool Enter()

Parameters:

• (none)

Return Value: true on success.

Usage Instruction: Required before creating objects/arrays/functions/dates asynchronously (outside a handler callback). Pair with Exit() — must be matched 1:1.

Threading Constraint: Owning thread only.

virtual bool Exit()

Return Value: undo one Enter(). Returns true on success. Owning thread only.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsSame(CefRefPtr<CefV8Context> that)

Return Value: true if same underlying handle.

Threading Constraint: Threading constraint not specified in source.

virtual bool Eval(const CefString& code, const CefString& script_url, int start_line, CefRefPtr<CefV8Value>& retval, CefRefPtr<CefV8Exception>& exception)

Parameters:

• code: JS source; script_url: optional origin URL for stack traces; start_line: 1-based line offset for error reporting; retval: out-param for the JS return value; exception: out-param populated on failure.

Return Value: true on success (retval populated); false on failure (exception populated).

Threading Constraint: Owning thread only, with context entered.

Usage Example

// Capture a context during OnContextCreated, then re-enter it later from another thread.
class MyHandler : public CefRenderProcessHandler {
  void OnContextCreated(CefRefPtr<CefBrowser> b, CefRefPtr<CefFrame> f,
                        CefRefPtr<CefV8Context> ctx) override {
    stored_ctx_ = ctx;
  }
  void CallJsLater() {
    stored_ctx_->GetTaskRunner()->PostTask(new MyTask(stored_ctx_));
  }
  CefRefPtr<CefV8Context> stored_ctx_;
};

class MyTask : public CefTask {
  CefRefPtr<CefV8Context> ctx_;
  void Execute() override {
    if (ctx_->Enter()) {
      CefRefPtr<CefV8Value> g = ctx_->GetGlobal();
      CefRefPtr<CefV8Value> fn = g->GetValue("myFn");
      CefV8ValueList args; args.push_back(CefV8Value::CreateInt(42));
      fn->ExecuteFunction(g, args);
      ctx_->Exit();
    }
  }
};

CefV8Handler (USER-IMPLEMENTED)

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — invoked on the thread that owns the V8 context (TID_RENDERER or a WebWorker).

Purpose: Implement this interface to receive native function calls dispatched by native function X() declarations in CefRegisterExtension JS code, or by CefV8Value::CreateFunction().

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

virtual bool Execute(const CefString& name, CefRefPtr<CefV8Value> object, const CefV8ValueList& arguments, CefRefPtr<CefV8Value>& retval, CefString& exception) = 0

Parameters:

• name: function name as declared in JS ("MyFunction" not "example.test.myFunction").
• object: the receiver (this) of the call.
• arguments: list of CefV8Value arguments.
• retval: out-param — set to the JS return value on success.
• exception: out-param — set to a JS exception message string on failure.

Return Value: true if execution was handled (retval or exception will be propagated to JS); false if not handled (JS will see no return value).

Usage Instruction: This is the heart of the JS→C++ bridge. Do not retain object or arguments past the call (V8 may GC them).

Threading Constraint: Called on the thread associated with the V8 function.

Usage Example

class NativeEchoHandler : public CefV8Handler {
 public:
  bool Execute(const CefString& name,
               CefRefPtr<CefV8Value> object,
               const CefV8ValueList& arguments,
               CefRefPtr<CefV8Value>& retval,
               CefString& exception) override {
    if (name == "Echo") {
      if (arguments.empty()) { exception = "Echo requires 1 arg"; return true; }
      retval = arguments[0];  // echo back the first argument
      return true;
    }
    return false;  // unknown function — let other handlers try
  }
  IMPLEMENT_REFCOUNTING(NativeEchoHandler);
};

// Register inside CefRenderProcessHandler::OnWebKitInitialized:
CefRegisterExtension("v8/echo",
  "if (!window.echo) window.echo = {};"
  "window.echo.run = function(x) { native function Echo(); return Echo(x); };",
  new NativeEchoHandler);

CefV8Accessor (USER-IMPLEMENTED)

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — invoked on the thread of the owning V8 context.

Purpose: Implement to intercept JS property gets/sets on an object created with CefV8Value::CreateObject(accessor, ...). Identifiers are registered via CefV8Value::SetValue(key, PropertyAttribute).

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

virtual bool Get(const CefString& name, const CefRefPtr<CefV8Value> object, CefRefPtr<CefV8Value>& retval, CefString& exception) = 0

Parameters:

• name: property name; object: receiver; retval: out value on success; exception: out message on failure.

Return Value: true if retrieval was handled.

Threading Constraint: Owning V8 thread.

virtual bool Set(const CefString& name, const CefRefPtr<CefV8Value> object, const CefRefPtr<CefV8Value> value, CefString& exception) = 0

Parameters:

• name: property name; object: receiver; value: new value; exception: out message on failure.

Return Value: true if assignment was handled.

Threading Constraint: Owning V8 thread.

Usage Example

class BoundAccessor : public CefV8Accessor {
 public:
  bool Get(const CefString& name, const CefRefPtr<CefV8Value> object,
           CefRefPtr<CefV8Value>& retval, CefString& exception) override {
    if (name == "counter") { retval = CefV8Value::CreateInt(counter_); return true; }
    return false;
  }
  bool Set(const CefString& name, const CefRefPtr<CefV8Value> object,
           const CefRefPtr<CefV8Value> value, CefString& exception) override {
    if (name == "counter" && value->IsInt()) { counter_ = value->GetIntValue(); return true; }
    return false;
  }
 private:
  int counter_ = 0;
  IMPLEMENT_REFCOUNTING(BoundAccessor);
};

// In a V8 handler callback (or after ctx->Enter()):
CefRefPtr<CefV8Accessor> acc = new BoundAccessor();
CefRefPtr<CefV8Value> obj = CefV8Value::CreateObject(acc, nullptr);
obj->SetValue("counter", V8_PROPERTY_ATTRIBUTE_NONE);
// JS code can now read/write obj.counter and have it routed to BoundAccessor.

CefV8Interceptor (USER-IMPLEMENTED)

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — invoked on the owning V8 thread.

Purpose: Implement to intercept all named and indexed property accesses on an object created with CefV8Value::CreateObject(nullptr, interceptor). Unlike CefV8Accessor, interceptors fire for every property, not just pre-registered ones.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

virtual bool Get(const CefString& name, const CefRefPtr<CefV8Value> object, CefRefPtr<CefV8Value>& retval, CefString& exception) = 0

Parameters:

• name: property name (string-keyed access — obj.foo).

Return Value: true if retrieval was handled. If property doesn't exist, do not set retval or exception and return true. If retrieval fails, set exception and return true. If the property has an associated accessor, it is called only if retval is not set.

Threading Constraint: Owning V8 thread.

virtual bool Get(int index, const CefRefPtr<CefV8Value> object, CefRefPtr<CefV8Value>& retval, CefString& exception) = 0

Parameters:

• index: integer-keyed access (obj[3]).

Return Value: Same protocol as the string-keyed overload.

Threading Constraint: Owning V8 thread.

virtual bool Set(const CefString& name, const CefRefPtr<CefV8Value> object, const CefRefPtr<CefV8Value> value, CefString& exception) = 0

Parameters:

• name, object, value: as above. This setter is always called, even when an accessor is also registered.

Return Value: true if assignment handled.

Threading Constraint: Owning V8 thread.

virtual bool Set(int index, const CefRefPtr<CefV8Value> object, const CefRefPtr<CefV8Value> value, CefString& exception) = 0

Return Value: same protocol as above, integer-keyed. Owning V8 thread.

Threading Constraint: Threading constraint not specified in source.

Usage Example

class DictionaryBackedInterceptor : public CefV8Interceptor {
 public:
  bool Get(const CefString& name, const CefRefPtr<CefV8Value> obj,
           CefRefPtr<CefV8Value>& retval, CefString& ex) override {
    auto it = map_.find(name.ToString());
    if (it == map_.end()) return true;  // property doesn't exist
    retval = CefV8Value::CreateString(it->second);
    return true;
  }
  bool Get(int index, const CefRefPtr<CefV8Value> obj,
           CefRefPtr<CefV8Value>& retval, CefString& ex) override { return true; }
  bool Set(const CefString& name, const CefRefPtr<CefV8Value> obj,
           const CefRefPtr<CefV8Value> value, CefString& ex) override {
    if (value->IsString()) map_[name.ToString()] = value->GetStringValue().ToString();
    return true;
  }
  bool Set(int, const CefRefPtr<CefV8Value>, const CefRefPtr<CefV8Value>, CefString&) override {
    return true;
  }
 private:
  std::map<std::string, std::string> map_;
  IMPLEMENT_REFCOUNTING(DictionaryBackedInterceptor);
};

CefV8Exception

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — methods callable on any render-process thread.

Purpose: Read-only description of a V8 exception (returned by CefV8Context::Eval and CefV8Value::GetException).

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

virtual CefString GetMessage()

Return Value: exception message text.

Threading Constraint: Threading constraint not specified in source.

virtual CefString GetSourceLine()

Return Value: line of source code where exception occurred.

Threading Constraint: Threading constraint not specified in source.

virtual CefString GetScriptResourceName()

Return Value: origin resource name.

Threading Constraint: Threading constraint not specified in source.

virtual int GetLineNumber()

Return Value: 1-based line of error, 0 if unknown.

Threading Constraint: Threading constraint not specified in source.

virtual int GetStartPosition()

Return Value: character offset of start of error in script.

Threading Constraint: Threading constraint not specified in source.

virtual int GetEndPosition()

Return Value: character offset of end of error.

Threading Constraint: Threading constraint not specified in source.

virtual int GetStartColumn()

Return Value: column offset within line of error start.

Threading Constraint: Threading constraint not specified in source.

virtual int GetEndColumn()

Return Value: column offset within line of error end.

Threading Constraint: Threading constraint not specified in source.

Usage Example

CefRefPtr<CefV8Value> rv;
CefRefPtr<CefV8Exception> ex;
if (!ctx->Eval("throw new Error('boom');", "test.js", 1, rv, ex)) {
  LOG(INFO) << "JS threw: " << ex->GetMessage().ToString()
            << " at line " << ex->GetLineNumber();
}

CefV8ArrayBufferReleaseCallback (USER-IMPLEMENTED)

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — ReleaseBuffer is invoked on V8's GC thread when an externalized ArrayBuffer is collected.

Purpose: Provides the cleanup hook for CefV8Value::CreateArrayBuffer(buffer, length, callback) so the caller can free the underlying memory when V8 GCs the JS ArrayBuffer.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

virtual void ReleaseBuffer(void* buffer) = 0

Parameters:

• buffer: the exact pointer originally passed to CreateArrayBuffer.

Return Value: (none)

Usage Instruction: Free buffer here (e.g., delete[] static_cast<char*>(buffer) or free(buffer)). Must not access the buffer afterwards.

Threading Constraint: V8 GC thread (renderer process).

Usage Example

class MallocRelease : public CefV8ArrayBufferReleaseCallback {
 public:
  void ReleaseBuffer(void* buffer) override { std::free(buffer); }
  IMPLEMENT_REFCOUNTING(MallocRelease);
};

void* buf = std::malloc(1024);
std::memset(buf, 0xAB, 1024);
CefRefPtr<CefV8Value> ab =
    CefV8Value::CreateArrayBuffer(buf, 1024, new MallocRelease);
// JS ArrayBuffer 'ab' will call ReleaseBuffer(buf) when GCed.

CefV8BackingStore (added in CEF 14600)

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — created on a V8-isolate thread (renderer main thread or WebWorker). Once created, Data() is safe to read/write from any thread.

Purpose: Backing-store abstraction for ArrayBuffer. Allocate on a V8 thread, fill it on a background thread (e.g., do the expensive memcpy off-thread), then create the ArrayBuffer on the V8 thread via CefV8Value::CreateArrayBufferFromBackingStore(). Consumed and invalidated by that call.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

static CefRefPtr<CefV8BackingStore> Create(size_t byte_length)

Parameters:

• byte_length: number of bytes to allocate (uninitialized).

Return Value: New backing store or nullptr on failure.

Threading Constraint: Must be called on a thread with a valid V8 isolate. Returned object is safe to pass to any thread.

virtual void* Data()

Parameters:

• (none)

Return Value: Pointer to allocated memory; nullptr if consumed/invalid.

Usage Instruction: Caller must ensure all writes are complete before passing to CreateArrayBufferFromBackingStore. Do not retain this pointer after consumption.

Threading Constraint: Safe to read/write from any thread.

virtual size_t ByteLength()

Return Value: size in bytes, or 0 if consumed. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsValid()

Return Value: true until consumed by CreateArrayBufferFromBackingStore(). Any thread.

Threading Constraint: Threading constraint not specified in source.

Usage Example

// Background thread: allocate + fill the backing store.
CefRefPtr<CefV8BackingStore> store = CefV8BackingStore::Create(64 * 1024);
std::memcpy(store->Data(), src_data, 64 * 1024);

// V8 thread: wrap as ArrayBuffer (zero-copy).
CefRefPtr<CefV8Value> ab = CefV8Value::CreateArrayBufferFromBackingStore(store);
// store->IsValid() now returns false; store->Data() now returns nullptr.

CefV8Value

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — TID_RENDERER or WebWorker thread that owns the underlying V8 handle. Many factory methods may only be called inside a CefRenderProcessHandler / CefV8Handler / CefV8Accessor callback, or between matched CefV8Context::Enter() / Exit() calls on a stored context.

Purpose: The polymorphic V8 value handle. Covers all JS types: undefined/null/bool/int/uint/double/date/string/object/array/ArrayBuffer/function/Promise. The class is the entire JS↔C++ data boundary — all values flowing across CefV8Handler::Execute, property access, and function invocation are CefV8Values.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

static CefRefPtr<CefV8Value> CreateUndefined()

Return Value: JS undefined. Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateNull()

Return Value: JS null. Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateBool(bool value)

Return Value: JS true/false. Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateInt(int32_t value)

Return Value: JS number (int). Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateUInt(uint32_t value)

Return Value: JS number (uint). Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateDouble(double value)

Return Value: JS number. Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateDate(CefBaseTime date)

Return Value: JS Date. Must be called inside a handler callback or after Enter(). Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateString(const CefString& value)

Return Value: JS string (empty allowed via optional_param). Owning thread.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateObject(CefRefPtr<CefV8Accessor> accessor, CefRefPtr<CefV8Interceptor> interceptor)

Parameters:

• accessor: optional property getter/setter; interceptor: optional named+indexed interceptor. Both may be nullptr.

Return Value: New user-created object. Must be called inside handler scope or with Enter()/Exit().

Threading Constraint: Owning thread, valid V8 context entered.

static CefRefPtr<CefV8Value> CreateArray(int length)

Parameters:

• length: array length; negative → length 0.

Threading Constraint: Owning thread, valid V8 context entered.

static CefRefPtr<CefV8Value> CreateArrayBuffer(void* buffer, size_t length, CefRefPtr<CefV8ArrayBufferReleaseCallback> release_callback)

Parameters:

• buffer: caller-owned memory of length bytes; release_callback: invoked when V8 GCs the ArrayBuffer. buffer may be nullptr (optional_param).

Return Value: Externalized ArrayBuffer wrapping buffer. Returns nullptr when V8 sandbox is enabled.

Threading Constraint: Owning thread, valid V8 context entered.

static CefRefPtr<CefV8Value> CreateArrayBufferWithCopy(void* buffer, size_t length)

Return Value: copies buffer into V8-managed memory (no release callback needed). Owning thread, valid V8 context entered.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreateFunction(const CefString& name, CefRefPtr<CefV8Handler> handler)

Parameters:

• name: function name (visible to JS stack traces); handler: receives calls.

Return Value: JS Function value. Owning thread, valid V8 context entered.

Threading Constraint: Threading constraint not specified in source.

static CefRefPtr<CefV8Value> CreatePromise()

Return Value: empty JS Promise; resolve/reject via ResolvePromise / RejectPromise. Owning thread, valid V8 context entered.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsValid()

Return Value: handle usable on current thread? Don't call other methods if false.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsSame(CefRefPtr<CefV8Value> that)

Return Value: true if same underlying V8 handle.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsUserCreated()

Return Value: true if created by CreateObject (vs. built-in).

Threading Constraint: Threading constraint not specified in source.

virtual bool HasException()

Return Value: true if last method call raised a V8 exception (scoped to this CefV8Value).

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8Exception> GetException()

Return Value: last exception object.

Threading Constraint: Threading constraint not specified in source.

virtual bool ClearException()

Return Value: clear last exception, returns true on success.

Threading Constraint: Threading constraint not specified in source.

virtual bool WillRethrowExceptions()

Return Value: true if exceptions will be re-thrown.

Threading Constraint: Threading constraint not specified in source.

virtual bool SetRethrowExceptions(bool rethrow)

Return Value: toggle re-throw; default false. Don't access context again until caught.

Threading Constraint: Threading constraint not specified in source.

virtual bool HasValue(const CefString& key)

Return Value: true if object has property key (string-keyed). key is optional_param.

Threading Constraint: Threading constraint not specified in source.

virtual bool HasValue(int index)

Return Value: integer-keyed variant.

Threading Constraint: Threading constraint not specified in source.

virtual bool DeleteValue(const CefString& key)

Return Value: delete property; returns true even for read-only/don't-delete (silent failure). key is optional_param.

Threading Constraint: Threading constraint not specified in source.

virtual bool DeleteValue(int index)

Return Value: integer variant.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8Value> GetValue(const CefString& key)

Return Value: get property; nullptr on exception or wrong call. key is optional_param.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8Value> GetValue(int index)

Return Value: integer variant.

Threading Constraint: Threading constraint not specified in source.

virtual bool SetValue(const CefString& key, CefRefPtr<CefV8Value> value, PropertyAttribute attribute)

Return Value: set property; attribute controls read-only/dont-delete/dont-enum. key optional_param.

Threading Constraint: Threading constraint not specified in source.

virtual bool SetValue(int index, CefRefPtr<CefV8Value> value)

Return Value: integer variant.

Threading Constraint: Threading constraint not specified in source.

virtual bool SetValue(const CefString& key, PropertyAttribute attribute)

Return Value: register an accessor-backed identifier; routing goes to CefV8Accessor::Get/Set. key optional_param.

Threading Constraint: Threading constraint not specified in source.

virtual bool GetKeys(std::vector<CefString>& keys)

Return Value: fill vector with all keys (integer keys appear as strings).

Threading Constraint: Threading constraint not specified in source.

virtual bool SetUserData(CefRefPtr<CefBaseRefCounted> user_data)

Return Value: attach arbitrary ref-counted C++ data to a user-created object. Returns false if not user-created.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefBaseRefCounted> GetUserData()

Return Value: retrieve attached data.

Threading Constraint: Threading constraint not specified in source.

virtual int GetExternallyAllocatedMemory()

Return Value: bytes currently registered for this object's external memory.

Threading Constraint: Threading constraint not specified in source.

virtual int AdjustExternallyAllocatedMemory(int change_in_bytes)

Return Value: adjust the external-memory counter (helps V8 schedule GC). Returns new total for this object. Only on user-created objects.

Threading Constraint: Threading constraint not specified in source.

virtual int GetArrayLength()

Return Value: element count.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8ArrayBufferReleaseCallback> GetArrayBufferReleaseCallback()

Return Value: callback passed to CreateArrayBuffer, or nullptr if not externalized.

Threading Constraint: Threading constraint not specified in source.

virtual bool NeuterArrayBuffer()

Return Value: set ArrayBuffer length to 0 (irreversible); releases the buffer via the callback.

Threading Constraint: Threading constraint not specified in source.

virtual size_t GetArrayBufferByteLength()

Return Value: length in bytes.

Threading Constraint: Threading constraint not specified in source.

virtual void* GetArrayBufferData()

Return Value: pointer to backing memory, valid for the lifetime of this CefV8Value.

Threading Constraint: Threading constraint not specified in source.

virtual CefString GetFunctionName()

Return Value: function name.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8Handler> GetFunctionHandler()

Return Value: handler if CEF-created, else nullptr.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8Value> ExecuteFunction(CefRefPtr<CefV8Value> object, const CefV8ValueList& arguments)

Parameters:

• object: receiver (this); empty → use current context's global. arguments: list of args.

Return Value: Return value on success; nullptr on bad call or exception.

Threading Constraint: Inside CefV8Handler/CefV8Accessor callback or between Enter()/Exit().

virtual CefRefPtr<CefV8Value> ExecuteFunctionWithContext(CefRefPtr<CefV8Context> context, CefRefPtr<CefV8Value> object, const CefV8ValueList& arguments)

Return Value: execute in an explicit context. object empty → specified context's global.

Threading Constraint: Threading constraint not specified in source.

virtual bool ResolvePromise(CefRefPtr<CefV8Value> arg)

Return Value: resolve with arg (optional_param). Returns false on misuse or exception. Inside handler scope.

Threading Constraint: Threading constraint not specified in source.

virtual bool RejectPromise(const CefString& errorMsg)

Return Value: reject with error message. Inside handler scope.

Threading Constraint: Threading constraint not specified in source.

Usage Example

// 1) Implement a handler that exposes an async C++ operation as a JS Promise.
class AsyncHandler : public CefV8Handler {
 public:
  bool Execute(const CefString& name,
               CefRefPtr<CefV8Value> object,
               const CefV8ValueList& arguments,
               CefRefPtr<CefV8Value>& retval,
               CefString& exception) override {
    if (name != "ComputeAsync" || arguments.size() < 1 || !arguments[0]->IsInt()) {
      exception = "ComputeAsync(int) expected";
      return true;
    }
    int n = arguments[0]->GetIntValue();

    // Create a JS Promise and remember it for later resolution.
    CefRefPtr<CefV8Value> promise = CefV8Value::CreatePromise();
    // Post the heavy work to a worker thread; resolve promise from the V8 thread.
    CefPostTask(TID_RENDERER, new ResolvePromiseTask(promise, n));
    retval = promise;
    return true;
  }
  IMPLEMENT_REFCOUNTING(AsyncHandler);
};

class ResolvePromiseTask : public CefTask {
 public:
  ResolvePromiseTask(CefRefPtr<CefV8Value> p, int n) : p_(p), n_(n) {}
  void Execute() override {
    if (!p_->IsValid() || !p_->IsPromise()) return;
    long sq = (long)n_ * n_;
    p_->ResolvePromise(CefV8Value::CreateInt(static_cast<int32_t>(sq)));
  }
 private:
  CefRefPtr<CefV8Value> p_; int n_;
  IMPLEMENT_REFCOUNTING(ResolvePromiseTask);
};

// 2) Register and bind at context creation:
class MyRenderHandler : public CefRenderProcessHandler {
  void OnContextCreated(CefRefPtr<CefBrowser> b, CefRefPtr<CefFrame> f,
                        CefRefPtr<CefV8Context> ctx) override {
    CefRefPtr<CefV8Value> global = ctx->GetGlobal();
    global->SetValue("computeAsync",
                     CefV8Value::CreateFunction("computeAsync", new AsyncHandler),
                     V8_PROPERTY_ATTRIBUTE_NONE);
  }
};

// 3) From page JS: computeAsync(7).then(r => console.log(r));  // logs 49

CefV8StackTrace

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — created/accessed only on the owning V8 thread.

Purpose: Snapshot of the V8 call stack at the time GetCurrent() is called.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

static CefRefPtr<CefV8StackTrace> GetCurrent(int frame_limit)

Parameters:

• frame_limit: maximum number of frames to capture.

Return Value: Stack trace handle.

Threading Constraint: V8 thread (renderer or WebWorker).

virtual bool IsValid()

Return Value: handle usable on current thread?

Threading Constraint: Threading constraint not specified in source.

virtual int GetFrameCount()

Return Value: number of frames captured.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefV8StackFrame> GetFrame(int index)

Return Value: frame at 0-based index.

Threading Constraint: Threading constraint not specified in source.

Usage Example

// Inside a CefV8Handler::Execute for diagnostics:
CefRefPtr<CefV8StackTrace> st = CefV8StackTrace::GetCurrent(10);
for (int i = 0; i < st->GetFrameCount(); ++i) {
  CefRefPtr<CefV8StackFrame> f = st->GetFrame(i);
  LOG(INFO) << f->GetFunctionName().ToString() << " @ "
            << f->GetScriptName().ToString() << ":" << f->GetLineNumber();
}

CefV8StackFrame

Source File: include/cef_v8.h

Process / Thread Context: Renderer process — accessible on the owning V8 thread.

Purpose: One frame within a CefV8StackTrace.

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

virtual bool IsValid()

Return Value: usable on current thread?

Threading Constraint: Threading constraint not specified in source.

virtual CefString GetScriptName()

Return Value: script resource name.

Threading Constraint: Threading constraint not specified in source.

virtual CefString GetScriptNameOrSourceURL()

Return Value: script name, or sourceURL directive value if script ends with //@ sourceURL=....

Threading Constraint: Threading constraint not specified in source.

virtual CefString GetFunctionName()

Return Value: function name.

Threading Constraint: Threading constraint not specified in source.

virtual int GetLineNumber()

Return Value: 1-based line, 0 if unknown.

Threading Constraint: Threading constraint not specified in source.

virtual int GetColumn()

Return Value: 1-based column, 0 if unknown.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsEval()

Return Value: true if function compiled via eval().

Threading Constraint: Threading constraint not specified in source.

virtual bool IsConstructor()

Return Value: true if called with new.

Threading Constraint: Threading constraint not specified in source.

See Also

• cef_values
• cef_process_message
• cef_render_process_handler