CefBaseScoped

Header: cef_base.h
Sections: CefBaseRefCounted, CefBaseScoped, CefRefCount (+1 more)
Category: Core APIs

Overview

Foundational interfaces: process bootstrap, browser lifecycle, frames, DOM, requests, and data objects.

CefBaseRefCounted

Source File: include/cef_base.h

Process / Thread Context: Not applicable — this is a universal base class instantiated in every CEF process (Browser, Renderer, GPU, Utility, etc.) and on every thread.

Purpose: Per the header comment, "All ref-counted framework classes must extend this class." It declares the four-method atomic reference-counting contract that every CEF interface (e.g. CefBrowser, CefFrame, CefClient, CefApp) inherits from. Concrete subclasses obtain an implementation of these methods by using the IMPLEMENT_REFCOUNTING(ClassName) macro, which composes in a CefRefCount member and overrides the four virtuals.

Methods

virtual void AddRef() const = 0

Parameters:

• none.

Return Value: void. "Called to increment the reference count for the object. Should be called for every new copy of a pointer to a given object."

Usage Instruction: Called automatically by CefRefPtr (the smart-pointer wrapper from include/internal/cef_ptr.h). Application code rarely invokes this directly unless managing raw pointers manually. Pair every AddRef with a matching Release.

Threading Constraint: Thread-safe by contract — must be implementable on any thread (the IMPLEMENT_REFCOUNTING macro backs it with base::AtomicRefCount).

virtual bool Release() const = 0

Parameters:

• none.

Return Value: bool. "Called to decrement the reference count for the object. Returns true if the reference count is 0, in which case the object should self-delete."

Usage Instruction: Drop one reference. A true return means the object has just been (or is about to be) destroyed; the caller must not touch the object again. The IMPLEMENT_REFCOUNTING macro turns a true return into an immediate delete static_cast<const ClassName*>(this).

Threading Constraint: Thread-safe; designed to be called from any thread.

virtual bool HasOneRef() const = 0

Parameters:

• none.

Return Value: "Returns true if the reference count is 1."

Usage Instruction: Useful for asserting exclusive ownership before mutating an object in-place. The CEF internals use it to detect single-owner fast paths.

Threading Constraint: Thread-safe read.

virtual bool HasAtLeastOneRef() const = 0

Parameters:

• none.

Return Value: "Returns true if the reference count is at least 1."

Usage Instruction: Used to check liveness without committing to an AddRef. Useful in shutdown paths where you need to know whether the object is still owned by someone.

Threading Constraint: Thread-safe read.

Usage Example

// You never instantiate CefBaseRefCounted directly — you inherit from it
// indirectly through CefBrowser, CefFrame, CefClient, CefApp, etc.
// The pattern below shows what IMPLEMENT_REFCOUNTING injects:

class MyHandler : public CefBaseRefCounted {
 public:
  MyHandler() = default;

  // The macro below privately adds a CefRefCount member and overrides
  // AddRef/Release/HasOneRef/HasAtLeastOneRef to delegate to it.
  IMPLEMENT_REFCOUNTING(MyHandler);

 public:
  void DoWork() { /* ... */ }
};

// CefRefPtr<MyHandler> uses AddRef/Release automatically:
CefRefPtr<MyHandler> handler = new MyHandler();  // AddRef -> count=1
CefRefPtr<MyHandler> copy = handler;             // AddRef -> count=2
copy = nullptr;                                   // Release -> count=1
handler = nullptr;                                 // Release -> count=0 -> delete

CefBaseScoped

Source File: include/cef_base.h

Process / Thread Context: Universal base; used in any process/thread that holds a scoped CEF handle.

Purpose: "All scoped framework classes must extend this class." Unlike CefBaseRefCounted, scoped CEF objects are not ref-counted — they are owned by a single C++ scope and destroyed when that scope exits (RAII). The class only declares a virtual destructor; subclasses add real methods.

Usage Example

// Scoped CEF handles (e.g. CefScopedLibraryLoader) derive from CefBaseScoped.
// They are stack-allocated and self-cleaning; no CefRefPtr needed.
class MyScopedResource : public CefBaseScoped {
 public:
  MyScopedResource() { Acquire(); }
  ~MyScopedResource() { Release(); }
 private:
  void Acquire();
  void Release();
};

{
  MyScopedResource r;  // ctor acquires
}  // dtor releases — no AddRef/Release dance

CefRefCount

Source File: include/cef_base.h

Process / Thread Context: Used inside any IMPLEMENT_REFCOUNTING-derived class, on any thread.

Purpose: "Class that implements atomic reference counting." It wraps base::AtomicRefCount and exposes the four methods that IMPLEMENT_REFCOUNTING plugs into CefBaseRefCounted. Application code does not use CefRefCount directly — it is an internal helper.

Methods

void AddRef() const

Return Value: void. Increments the internal atomic counter.

Usage Instruction: Called by the IMPLEMENT_REFCOUNTING override of CefBaseRefCounted::AddRef.

Threading Constraint: Thread-safe via base::AtomicRefCount::Increment.

bool Release() const

Return Value: bool. "Decrement the reference count. Returns true if the reference count is 0." Note: the implementation reads return !ref_count_.Decrement(); — the wrapper inverts the AtomicRefCount convention so a true result means "the count is now zero, please delete".

Usage Instruction: Called by the macro's Release override.

Threading Constraint: Thread-safe.

bool HasOneRef() const

Return Value: bool. True when the count is exactly 1.

Usage Instruction: Used by the macro's HasOneRef override.

Threading Constraint: Thread-safe.

bool HasAtLeastOneRef() const

Return Value: bool. True when the count is ≥ 1.

Usage Instruction: Used by the macro's HasAtLeastOneRef override.

Threading Constraint: Thread-safe.

int SubtleRefCountForDebug() const

Return Value: "Returns the current reference count (with no barriers). This is subtle, and should be used only for debugging."

Usage Instruction: Diagnostic only — never use to drive logic.

Threading Constraint: Returns a non-synchronized snapshot.

Usage Example

// Direct use is rare; the macro composes it in for you.
class Manual : public CefBaseRefCounted {
 public:
  void AddRef() const override { rc_.AddRef(); }
  bool Release() const override {
    if (rc_.Release()) { delete this; return true; }
    return false;
  }
  bool HasOneRef() const override { return rc_.HasOneRef(); }
  bool HasAtLeastOneRef() const override { return rc_.HasAtLeastOneRef(); }
 private:
  CefRefCount rc_;
};
// Functionally identical to: IMPLEMENT_REFCOUNTING(Manual);

IMPLEMENT_REFCOUNTING(ClassName) Macro

Source File: include/cef_base.h

Purpose: Per the header, "Macro that provides a reference counting implementation for classes extending CefBase." It expands to four override methods (delegating to a privately-added CefRefCount ref_count_ member). On a Release() that returns true from CefRefCount::Release, it deletes static_cast<const ClassName*>(this) — the cast is what allows the macro to delete the most-derived type without a virtual destructor lookup ambiguity.

Usage Example

#include "include/cef_app.h"

class MyApp : public CefApp {
 public:
  MyApp() = default;

  // OnBeforeCommandLineProcessing, GetBrowserProcessHandler, etc. ...

 private:
  IMPLEMENT_REFCOUNTING(MyApp);
};

// Then pass into CefInitialize / CefExecuteProcess:
CefRefPtr<CefApp> app = new MyApp();
CefExecuteProcess(main_args, app, nullptr);