bcarrella/cef
1
0
Fork 0
mirror of https://bitbucket.org/chromiumembedded/cef synced 2025-02-16 12:10:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

Format include/base comments for Doxygen (see issue #3384)

Browse Source
This commit is contained in:
Marshall Greenblatt 2022-09-05 16:17:57 -04:00
parent cf7e10aacc
commit 12fc72147c
22 changed files with 1316 additions and 1061 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Doxyfile
View File

@ -1038,8 +1038,7 @@ EXCLUDE_PATTERNS = *_internal.h
# Note that the wildcards are matched against the file with absolute path, so to
# exclude all test directories use the pattern */test/*
EXCLUDE_SYMBOLS = base::cef_internal \
base::cef_subtle \
EXCLUDE_SYMBOLS = base::cef_subtle \
base::internal \
cef_trace_event \
cef::logging

27
include/base/cef_atomic_flag.h
View File

@ -49,9 +49,11 @@
namespace base {
// A flag that can safely be set from one thread and read from other threads.
//
// This class IS NOT intended for synchronization between threads.
///
/// A flag that can safely be set from one thread and read from other threads.
///
/// This class IS NOT intended for synchronization between threads.
///
class AtomicFlag {
public:
AtomicFlag();
@ -61,19 +63,26 @@ class AtomicFlag {
~AtomicFlag();
// Set the flag. Must always be called from the same thread.
///
/// Set the flag. Must always be called from the same thread.
///
void Set();
// Returns true iff the flag was set. If this returns true, the current thread
// is guaranteed to be synchronized with all memory operations on the thread
// which invoked Set() up until at least the first call to Set() on it.
///
/// Returns true iff the flag was set. If this returns true, the current
/// thread is guaranteed to be synchronized with all memory operations on the
/// thread which invoked Set() up until at least the first call to Set() on
/// it.
///
bool IsSet() const {
// Inline here: this has a measurable performance impact on base::WeakPtr.
return flag_.load(std::memory_order_acquire) != 0;
}
// Resets the flag. Be careful when using this: callers might not expect
// IsSet() to return false after returning true once.
///
/// Resets the flag. Be careful when using this: callers might not expect
/// IsSet() to return false after returning true once.
///
void UnsafeResetForTesting();
private:

48
include/base/cef_atomic_ref_count.h
View File

@ -58,19 +58,25 @@ class AtomicRefCount {
explicit constexpr AtomicRefCount(int initial_value)
: ref_count_(initial_value) {}
// Increment a reference count.
// Returns the previous value of the count.
///
/// Increment a reference count.
/// Returns the previous value of the count.
///
int Increment() { return Increment(1); }
// Increment a reference count by "increment", which must exceed 0.
// Returns the previous value of the count.
///
/// Increment a reference count by "increment", which must exceed 0.
/// Returns the previous value of the count.
///
int Increment(int increment) {
return ref_count_.fetch_add(increment, std::memory_order_relaxed);
}
// Decrement a reference count, and return whether the result is non-zero.
// Insert barriers to ensure that state written before the reference count
// became zero will be visible to a thread that has just made the count zero.
///
/// Decrement a reference count, and return whether the result is non-zero.
/// Insert barriers to ensure that state written before the reference count
/// became zero will be visible to a thread that has just made the count zero.
///
bool Decrement() {
// TODO(jbroman): Technically this doesn't need to be an acquire operation
// unless the result is 1 (i.e., the ref count did indeed reach zero).
@ -79,23 +85,29 @@ class AtomicRefCount {
return ref_count_.fetch_sub(1, std::memory_order_acq_rel) != 1;
}
// Return whether the reference count is one. If the reference count is used
// in the conventional way, a refrerence count of 1 implies that the current
// thread owns the reference and no other thread shares it. This call
// performs the test for a reference count of one, and performs the memory
// barrier needed for the owning thread to act on the object, knowing that it
// has exclusive access to the object.
///
/// Return whether the reference count is one. If the reference count is used
/// in the conventional way, a refrerence count of 1 implies that the current
/// thread owns the reference and no other thread shares it. This call
/// performs the test for a reference count of one, and performs the memory
/// barrier needed for the owning thread to act on the object, knowing that it
/// has exclusive access to the object.
///
bool IsOne() const { return ref_count_.load(std::memory_order_acquire) == 1; }
// Return whether the reference count is zero. With conventional object
// referencing counting, the object will be destroyed, so the reference count
// should never be zero. Hence this is generally used for a debug check.
///
/// Return whether the reference count is zero. With conventional object
/// referencing counting, the object will be destroyed, so the reference count
/// should never be zero. Hence this is generally used for a debug check.
///
bool IsZero() const {
return ref_count_.load(std::memory_order_acquire) == 0;
}
// Returns the current reference count (with no barriers). This is subtle, and
// should be used only for debugging.
///
/// Returns the current reference count (with no barriers). This is subtle,
/// and should be used only for debugging.
///
int SubtleRefCountForDebug() const {
return ref_count_.load(std::memory_order_relaxed);
}

404
include/base/cef_bind.h
View File

@ -28,41 +28,42 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// -----------------------------------------------------------------------------
// Usage documentation
// -----------------------------------------------------------------------------
//
// Overview:
// base::BindOnce() and base::BindRepeating() are helpers for creating
// base::OnceCallback and base::RepeatingCallback objects respectively.
//
// For a runnable object of n-arity, the base::Bind*() family allows partial
// application of the first m arguments. The remaining n - m arguments must be
// passed when invoking the callback with Run().
//
// // The first argument is bound at callback creation; the remaining
// // two must be passed when calling Run() on the callback object.
// base::OnceCallback<long(int, long)> cb = base::BindOnce(
// [](short x, int y, long z) { return x * y * z; }, 42);
//
// When binding to a method, the receiver object must also be specified at
// callback creation time. When Run() is invoked, the method will be invoked on
// the specified receiver object.
//
// class C : public base::RefCounted<C> { void F(); };
// auto instance = base::MakeRefCounted<C>();
// auto cb = base::BindOnce(&C::F, instance);
// std::move(cb).Run(); // Identical to instance->F()
//
// See //docs/callback.md for the full documentation.
//
// -----------------------------------------------------------------------------
///
/// \file
/// base::BindOnce() and base::BindRepeating() are helpers for creating
/// base::OnceCallback and base::RepeatingCallback objects respectively.
///
/// For a runnable object of n-arity, the base::Bind*() family allows partial
/// application of the first m arguments. The remaining n - m arguments must be
/// passed when invoking the callback with Run().
///
/// <pre>
/// // The first argument is bound at callback creation; the remaining
/// // two must be passed when calling Run() on the callback object.
/// base::OnceCallback<long(int, long)> cb = base::BindOnce(
/// [](short x, int y, long z) { return x * y * z; }, 42);
/// </pre>
///
/// When binding to a method, the receiver object must also be specified at
/// callback creation time. When Run() is invoked, the method will be invoked on
/// the specified receiver object.
///
/// <pre>
/// class C : public base::RefCounted<C> { void F(); };
/// auto instance = base::MakeRefCounted<C>();
/// auto cb = base::BindOnce(&C::F, instance);
/// std::move(cb).Run(); // Identical to instance->F()
/// </pre>
///
/// See https://chromium.googlesource.com/chromium/src/+/lkgr/docs/callback.md
/// for the full documentation.
///
// Implementation notes
// -----------------------------------------------------------------------------
//
// If you're reading the implementation, before proceeding further, you should
// read the top comment of base/internal/cef_bind_internal.h for a definition of
// common terms and concepts.
// read the top comment of base/internal/cef_bind_internal.h for a definition
// of common terms and concepts.
#ifndef CEF_INCLUDE_BASE_CEF_BIND_H_
#define CEF_INCLUDE_BASE_CEF_BIND_H_
@ -92,7 +93,9 @@
namespace base {
// Bind as OnceCallback.
///
/// Bind as OnceCallback.
///
template <typename Functor, typename... Args>
inline OnceCallback<internal::MakeUnboundRunType<Functor, Args...>> BindOnce(
Functor&& functor,
@ -111,7 +114,9 @@ inline OnceCallback<internal::MakeUnboundRunType<Functor, Args...>> BindOnce(
std::forward<Args>(args)...);
}
// Bind as RepeatingCallback.
///
/// Bind as RepeatingCallback.
///
template <typename Functor, typename... Args>
inline RepeatingCallback<internal::MakeUnboundRunType<Functor, Args...>>
BindRepeating(Functor&& functor, Args&&... args) {
@ -123,9 +128,11 @@ BindRepeating(Functor&& functor, Args&&... args) {
std::forward<Args>(args)...);
}
// Special cases for binding to a base::Callback without extra bound arguments.
// We CHECK() the validity of callback to guard against null pointers
// accidentally ending up in posted tasks, causing hard-to-debug crashes.
///
/// Special cases for binding to a base::Callback without extra bound arguments.
/// We CHECK() the validity of callback to guard against null pointers
/// accidentally ending up in posted tasks, causing hard-to-debug crashes.
///
template <typename Signature>
OnceCallback<Signature> BindOnce(OnceCallback<Signature> callback) {
CHECK(callback);
@ -145,44 +152,54 @@ RepeatingCallback<Signature> BindRepeating(
return callback;
}
// Unretained() allows binding a non-refcounted class, and to disable
// refcounting on arguments that are refcounted objects.
//
// EXAMPLE OF Unretained():
//
// class Foo {
// public:
// void func() { cout << "Foo:f" << endl; }
// };
//
// // In some function somewhere.
// Foo foo;
// OnceClosure foo_callback =
// BindOnce(&Foo::func, Unretained(&foo));
// std::move(foo_callback).Run(); // Prints "Foo:f".
//
// Without the Unretained() wrapper on |&foo|, the above call would fail
// to compile because Foo does not support the AddRef() and Release() methods.
///
/// Unretained() allows binding a non-refcounted class, and to disable
/// refcounting on arguments that are refcounted objects.
///
/// EXAMPLE OF Unretained():
///
/// <pre>
/// class Foo {
/// public:
/// void func() { cout << "Foo:f" << endl; }
/// };
///
/// // In some function somewhere.
/// Foo foo;
/// OnceClosure foo_callback =
/// BindOnce(&Foo::func, Unretained(&foo));
/// std::move(foo_callback).Run(); // Prints "Foo:f".
/// </pre>
///
/// Without the Unretained() wrapper on |&foo|, the above call would fail
/// to compile because Foo does not support the AddRef() and Release() methods.
///
template <typename T>
inline internal::UnretainedWrapper<T> Unretained(T* o) {
return internal::UnretainedWrapper<T>(o);
}
// RetainedRef() accepts a ref counted object and retains a reference to it.
// When the callback is called, the object is passed as a raw pointer.
//
// EXAMPLE OF RetainedRef():
//
// void foo(RefCountedBytes* bytes) {}
//
// scoped_refptr<RefCountedBytes> bytes = ...;
// OnceClosure callback = BindOnce(&foo, base::RetainedRef(bytes));
// std::move(callback).Run();
//
// Without RetainedRef, the scoped_refptr would try to implicitly convert to
// a raw pointer and fail compilation:
//
// OnceClosure callback = BindOnce(&foo, bytes); // ERROR!
///
/// RetainedRef() accepts a ref counted object and retains a reference to it.
/// When the callback is called, the object is passed as a raw pointer.
///
/// EXAMPLE OF RetainedRef():
///
/// <pre>
/// void foo(RefCountedBytes* bytes) {}
///
/// scoped_refptr<RefCountedBytes> bytes = ...;
/// OnceClosure callback = BindOnce(&foo, base::RetainedRef(bytes));
/// std::move(callback).Run();
/// </pre>
///
/// Without RetainedRef, the scoped_refptr would try to implicitly convert to
/// a raw pointer and fail compilation:
///
/// <pre>
/// OnceClosure callback = BindOnce(&foo, bytes); // ERROR!
/// </pre>
///
template <typename T>
inline internal::RetainedRefWrapper<T> RetainedRef(T* o) {
return internal::RetainedRefWrapper<T>(o);
@ -192,26 +209,30 @@ inline internal::RetainedRefWrapper<T> RetainedRef(scoped_refptr<T> o) {
return internal::RetainedRefWrapper<T>(std::move(o));
}
// Owned() transfers ownership of an object to the callback resulting from
// bind; the object will be deleted when the callback is deleted.
//
// EXAMPLE OF Owned():
//
// void foo(int* arg) { cout << *arg << endl }
//
// int* pn = new int(1);
// RepeatingClosure foo_callback = BindRepeating(&foo, Owned(pn));
//
// foo_callback.Run(); // Prints "1"
// foo_callback.Run(); // Prints "1"
// *pn = 2;
// foo_callback.Run(); // Prints "2"
//
// foo_callback.Reset(); // |pn| is deleted. Also will happen when
// // |foo_callback| goes out of scope.
//
// Without Owned(), someone would have to know to delete |pn| when the last
// reference to the callback is deleted.
///
/// Owned() transfers ownership of an object to the callback resulting from
/// bind; the object will be deleted when the callback is deleted.
///
/// EXAMPLE OF Owned():
///
/// <pre>
/// void foo(int* arg) { cout << *arg << endl }
///
/// int* pn = new int(1);
/// RepeatingClosure foo_callback = BindRepeating(&foo, Owned(pn));
///
/// foo_callback.Run(); // Prints "1"
/// foo_callback.Run(); // Prints "1"
/// *pn = 2;
/// foo_callback.Run(); // Prints "2"
///
/// foo_callback.Reset(); // |pn| is deleted. Also will happen when
/// // |foo_callback| goes out of scope.
/// </pre>
///
/// Without Owned(), someone would have to know to delete |pn| when the last
/// reference to the callback is deleted.
///
template <typename T>
inline internal::OwnedWrapper<T> Owned(T* o) {
return internal::OwnedWrapper<T>(o);
@ -223,78 +244,89 @@ inline internal::OwnedWrapper<T, Deleter> Owned(
return internal::OwnedWrapper<T, Deleter>(std::move(ptr));
}
// OwnedRef() stores an object in the callback resulting from
// bind and passes a reference to the object to the bound function.
//
// EXAMPLE OF OwnedRef():
//
// void foo(int& arg) { cout << ++arg << endl }
//
// int counter = 0;
// RepeatingClosure foo_callback = BindRepeating(&foo, OwnedRef(counter));
//
// foo_callback.Run(); // Prints "1"
// foo_callback.Run(); // Prints "2"
// foo_callback.Run(); // Prints "3"
//
// cout << counter; // Prints "0", OwnedRef creates a copy of counter.
//
// Supports OnceCallbacks as well, useful to pass placeholder arguments:
//
// void bar(int& ignore, const std::string& s) { cout << s << endl }
//
// OnceClosure bar_callback = BindOnce(&bar, OwnedRef(0), "Hello");
//
// std::move(bar_callback).Run(); // Prints "Hello"
//
// Without OwnedRef() it would not be possible to pass a mutable reference to an
// object owned by the callback.
///
/// OwnedRef() stores an object in the callback resulting from
/// bind and passes a reference to the object to the bound function.
///
/// EXAMPLE OF OwnedRef():
///
/// <pre>
/// void foo(int& arg) { cout << ++arg << endl }
///
/// int counter = 0;
/// RepeatingClosure foo_callback = BindRepeating(&foo, OwnedRef(counter));
///
/// foo_callback.Run(); // Prints "1"
/// foo_callback.Run(); // Prints "2"
/// foo_callback.Run(); // Prints "3"
///
/// cout << counter; // Prints "0", OwnedRef creates a copy of counter.
/// </pre>
///
/// Supports OnceCallbacks as well, useful to pass placeholder arguments:
///
/// <pre>
/// void bar(int& ignore, const std::string& s) { cout << s << endl }
///
/// OnceClosure bar_callback = BindOnce(&bar, OwnedRef(0), "Hello");
///
/// std::move(bar_callback).Run(); // Prints "Hello"
/// </pre>
///
/// Without OwnedRef() it would not be possible to pass a mutable reference to
/// an object owned by the callback.
///
template <typename T>
internal::OwnedRefWrapper<std::decay_t<T>> OwnedRef(T&& t) {
return internal::OwnedRefWrapper<std::decay_t<T>>(std::forward<T>(t));
}
// Passed() is for transferring movable-but-not-copyable types (eg. unique_ptr)
// through a RepeatingCallback. Logically, this signifies a destructive transfer
// of the state of the argument into the target function. Invoking
// RepeatingCallback::Run() twice on a callback that was created with a Passed()
// argument will CHECK() because the first invocation would have already
// transferred ownership to the target function.
//
// Note that Passed() is not necessary with BindOnce(), as std::move() does the
// same thing. Avoid Passed() in favor of std::move() with BindOnce().
//
// EXAMPLE OF Passed():
//
// void TakesOwnership(std::unique_ptr<Foo> arg) { }
// std::unique_ptr<Foo> CreateFoo() { return std::make_unique<Foo>();
// }
//
// auto f = std::make_unique<Foo>();
//
// // |cb| is given ownership of Foo(). |f| is now NULL.
// // You can use std::move(f) in place of &f, but it's more verbose.
// RepeatingClosure cb = BindRepeating(&TakesOwnership, Passed(&f));
//
// // Run was never called so |cb| still owns Foo() and deletes
// // it on Reset().
// cb.Reset();
//
// // |cb| is given a new Foo created by CreateFoo().
// cb = BindRepeating(&TakesOwnership, Passed(CreateFoo()));
//
// // |arg| in TakesOwnership() is given ownership of Foo(). |cb|
// // no longer owns Foo() and, if reset, would not delete Foo().
// cb.Run(); // Foo() is now transferred to |arg| and deleted.
// cb.Run(); // This CHECK()s since Foo() already been used once.
//
// We offer 2 syntaxes for calling Passed(). The first takes an rvalue and is
// best suited for use with the return value of a function or other temporary
// rvalues. The second takes a pointer to the scoper and is just syntactic sugar
// to avoid having to write Passed(std::move(scoper)).
//
// Both versions of Passed() prevent T from being an lvalue reference. The first
// via use of enable_if, and the second takes a T* which will not bind to T&.
///
/// Passed() is for transferring movable-but-not-copyable types (eg. unique_ptr)
/// through a RepeatingCallback. Logically, this signifies a destructive
/// transfer of the state of the argument into the target function. Invoking
/// RepeatingCallback::Run() twice on a callback that was created with a
/// Passed() argument will CHECK() because the first invocation would have
/// already transferred ownership to the target function.
///
/// Note that Passed() is not necessary with BindOnce(), as std::move() does the
/// same thing. Avoid Passed() in favor of std::move() with BindOnce().
///
/// EXAMPLE OF Passed():
///
/// <pre>
/// void TakesOwnership(std::unique_ptr<Foo> arg) { }
/// std::unique_ptr<Foo> CreateFoo() { return std::make_unique<Foo>();
/// }
///
/// auto f = std::make_unique<Foo>();
///
/// // |cb| is given ownership of Foo(). |f| is now NULL.
/// // You can use std::move(f) in place of &f, but it's more verbose.
/// RepeatingClosure cb = BindRepeating(&TakesOwnership, Passed(&f));
///
/// // Run was never called so |cb| still owns Foo() and deletes
/// // it on Reset().
/// cb.Reset();
///
/// // |cb| is given a new Foo created by CreateFoo().
/// cb = BindRepeating(&TakesOwnership, Passed(CreateFoo()));
///
/// // |arg| in TakesOwnership() is given ownership of Foo(). |cb|
/// // no longer owns Foo() and, if reset, would not delete Foo().
/// cb.Run(); // Foo() is now transferred to |arg| and deleted.
/// cb.Run(); // This CHECK()s since Foo() already been used once.
/// </pre>
///
/// We offer 2 syntaxes for calling Passed(). The first takes an rvalue and is
/// best suited for use with the return value of a function or other temporary
/// rvalues. The second takes a pointer to the scoper and is just syntactic
/// sugar to avoid having to write Passed(std::move(scoper)).
///
/// Both versions of Passed() prevent T from being an lvalue reference. The
/// first via use of enable_if, and the second takes a T* which will not bind to
/// T&.
///
template <typename T,
std::enable_if_t<!std::is_lvalue_reference<T>::value>* = nullptr>
inline internal::PassedWrapper<T> Passed(T&& scoper) {
@ -305,21 +337,25 @@ inline internal::PassedWrapper<T> Passed(T* scoper) {
return internal::PassedWrapper<T>(std::move(*scoper));
}
// IgnoreResult() is used to adapt a function or callback with a return type to
// one with a void return. This is most useful if you have a function with,
// say, a pesky ignorable bool return that you want to use with PostTask or
// something else that expect a callback with a void return.
//
// EXAMPLE OF IgnoreResult():
//
// int DoSomething(int arg) { cout << arg << endl; }
//
// // Assign to a callback with a void return type.
// OnceCallback<void(int)> cb = BindOnce(IgnoreResult(&DoSomething));
// std::move(cb).Run(1); // Prints "1".
//
// // Prints "2" on |ml|.
// ml->PostTask(FROM_HERE, BindOnce(IgnoreResult(&DoSomething), 2);
///
/// IgnoreResult() is used to adapt a function or callback with a return type to
/// one with a void return. This is most useful if you have a function with,
/// say, a pesky ignorable bool return that you want to use with PostTask or
/// something else that expect a callback with a void return.
///
/// EXAMPLE OF IgnoreResult():
///
/// <pre>
/// int DoSomething(int arg) { cout << arg << endl; }
///
/// // Assign to a callback with a void return type.
/// OnceCallback<void(int)> cb = BindOnce(IgnoreResult(&DoSomething));
/// std::move(cb).Run(1); // Prints "1".
///
/// // Prints "2" on |ml|.
/// ml->PostTask(FROM_HERE, BindOnce(IgnoreResult(&DoSomething), 2);
/// </pre>
///
template <typename T>
inline internal::IgnoreResultHelper<T> IgnoreResult(T data) {
return internal::IgnoreResultHelper<T>(std::move(data));
@ -327,16 +363,20 @@ inline internal::IgnoreResultHelper<T> IgnoreResult(T data) {
#if defined(OS_APPLE) && !HAS_FEATURE(objc_arc)
// RetainBlock() is used to adapt an Objective-C block when Automated Reference
// Counting (ARC) is disabled. This is unnecessary when ARC is enabled, as the
// BindOnce and BindRepeating already support blocks then.
//
// EXAMPLE OF RetainBlock():
//
// // Wrap the block and bind it to a callback.
// OnceCallback<void(int)> cb =
// BindOnce(RetainBlock(^(int n) { NSLog(@"%d", n); }));
// std::move(cb).Run(1); // Logs "1".
///
/// RetainBlock() is used to adapt an Objective-C block when Automated Reference
/// Counting (ARC) is disabled. This is unnecessary when ARC is enabled, as the
/// BindOnce and BindRepeating already support blocks then.
///
/// EXAMPLE OF RetainBlock():
///
/// <pre>
/// // Wrap the block and bind it to a callback.
/// OnceCallback<void(int)> cb =
/// BindOnce(RetainBlock(^(int n) { NSLog(@"%d", n); }));
/// std::move(cb).Run(1); // Logs "1".
/// </pre>
///
template <typename R, typename... Args>
base::mac::ScopedBlock<R (^)(Args...)> RetainBlock(R (^block)(Args...)) {
return base::mac::ScopedBlock<R (^)(Args...)>(block,

64
include/base/cef_build.h
View File

@ -27,36 +27,40 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// This file adds defines about the platform we're currently building on.
//
// Operating System:
// OS_AIX / OS_ANDROID / OS_ASMJS / OS_FREEBSD / OS_FUCHSIA / OS_IOS /
// OS_LINUX / OS_MAC / OS_NACL (SFI or NONSFI) / OS_NETBSD / OS_OPENBSD /
// OS_QNX / OS_SOLARIS / OS_WIN
// Operating System family:
// OS_APPLE: IOS or MAC
// OS_BSD: FREEBSD or NETBSD or OPENBSD
// OS_POSIX: AIX or ANDROID or ASMJS or CHROMEOS or FREEBSD or IOS or LINUX
// or MAC or NACL or NETBSD or OPENBSD or QNX or SOLARIS
//
// /!\ Note: OS_CHROMEOS is set by the build system, not this file
//
// Compiler:
// COMPILER_MSVC / COMPILER_GCC
//
// Processor:
// ARCH_CPU_ARM64 / ARCH_CPU_ARMEL / ARCH_CPU_MIPS / ARCH_CPU_MIPS64 /
// ARCH_CPU_MIPS64EL / ARCH_CPU_MIPSEL / ARCH_CPU_PPC64 / ARCH_CPU_S390 /
// ARCH_CPU_S390X / ARCH_CPU_X86 / ARCH_CPU_X86_64
// Processor family:
// ARCH_CPU_ARM_FAMILY: ARMEL or ARM64
// ARCH_CPU_MIPS_FAMILY: MIPS64EL or MIPSEL or MIPS64 or MIPS
// ARCH_CPU_PPC64_FAMILY: PPC64
// ARCH_CPU_S390_FAMILY: S390 or S390X
// ARCH_CPU_X86_FAMILY: X86 or X86_64
// Processor features:
// ARCH_CPU_31_BITS / ARCH_CPU_32_BITS / ARCH_CPU_64_BITS
// ARCH_CPU_BIG_ENDIAN / ARCH_CPU_LITTLE_ENDIAN
/// \file
/// This file adds defines about the platform we're currently building on.
///
/// <pre>
/// Operating System:
/// OS_AIX / OS_ANDROID / OS_ASMJS / OS_FREEBSD / OS_FUCHSIA / OS_IOS /
/// OS_LINUX / OS_MAC / OS_NACL (SFI or NONSFI) / OS_NETBSD / OS_OPENBSD /
/// OS_QNX / OS_SOLARIS / OS_WIN
/// Operating System family:
/// OS_APPLE: IOS or MAC
/// OS_BSD: FREEBSD or NETBSD or OPENBSD
/// OS_POSIX: AIX or ANDROID or ASMJS or CHROMEOS or FREEBSD or IOS or LINUX
/// or MAC or NACL or NETBSD or OPENBSD or QNX or SOLARIS
///
/// /!\ Note: OS_CHROMEOS is set by the build system, not this file
///
/// Compiler:
/// COMPILER_MSVC / COMPILER_GCC
///
/// Processor:
/// ARCH_CPU_ARM64 / ARCH_CPU_ARMEL / ARCH_CPU_MIPS / ARCH_CPU_MIPS64 /
/// ARCH_CPU_MIPS64EL / ARCH_CPU_MIPSEL / ARCH_CPU_PPC64 / ARCH_CPU_S390 /
/// ARCH_CPU_S390X / ARCH_CPU_X86 / ARCH_CPU_X86_64
/// Processor family:
/// ARCH_CPU_ARM_FAMILY: ARMEL or ARM64
/// ARCH_CPU_MIPS_FAMILY: MIPS64EL or MIPSEL or MIPS64 or MIPS
/// ARCH_CPU_PPC64_FAMILY: PPC64
/// ARCH_CPU_S390_FAMILY: S390 or S390X
/// ARCH_CPU_X86_FAMILY: X86 or X86_64
/// Processor features:
/// ARCH_CPU_31_BITS / ARCH_CPU_32_BITS / ARCH_CPU_64_BITS
/// ARCH_CPU_BIG_ENDIAN / ARCH_CPU_LITTLE_ENDIAN
/// </pre>
///
#ifndef CEF_INCLUDE_BASE_CEF_BUILD_H_
#define CEF_INCLUDE_BASE_CEF_BUILD_H_

66
include/base/cef_callback.h
View File

@ -28,40 +28,38 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// -----------------------------------------------------------------------------
// Usage documentation
// -----------------------------------------------------------------------------
//
// Overview:
// A callback is similar in concept to a function pointer: it wraps a runnable
// object such as a function, method, lambda, or even another callback, allowing
// the runnable object to be invoked later via the callback object.
//
// Unlike function pointers, callbacks are created with base::BindOnce() or
// base::BindRepeating() and support partial function application.
//
// A base::OnceCallback may be Run() at most once; a base::RepeatingCallback may
// be Run() any number of times. |is_null()| is guaranteed to return true for a
// moved-from callback.
//
// // The lambda takes two arguments, but the first argument |x| is bound at
// // callback creation.
// base::OnceCallback<int(int)> cb = base::BindOnce([] (int x, int y) {
// return x + y;
// }, 1);
// // Run() only needs the remaining unbound argument |y|.
// printf("1 + 2 = %d\n", std::move(cb).Run(2)); // Prints 3
// printf("cb is null? %s\n",
// cb.is_null() ? "true" : "false"); // Prints true
// std::move(cb).Run(2); // Crashes since |cb| has already run.
//
// Callbacks also support cancellation. A common use is binding the receiver
// object as a WeakPtr<T>. If that weak pointer is invalidated, calling Run()
// will be a no-op. Note that |IsCancelled()| and |is_null()| are distinct:
// simply cancelling a callback will not also make it null.
//
// See https://chromium.googlesource.com/chromium/src/+/HEAD/docs/callback.md
// for the full documentation.
/// \file
/// A callback is similar in concept to a function pointer: it wraps a runnable
/// object such as a function, method, lambda, or even another callback,
/// allowing the runnable object to be invoked later via the callback object.
///
/// Unlike function pointers, callbacks are created with base::BindOnce() or
/// base::BindRepeating() and support partial function application.
///
/// A base::OnceCallback may be Run() at most once; a base::RepeatingCallback
/// may be Run() any number of times. |is_null()| is guaranteed to return true
/// for a moved-from callback.
///
/// <pre>
/// // The lambda takes two arguments, but the first argument |x| is bound at
/// // callback creation.
/// base::OnceCallback<int(int)> cb = base::BindOnce([] (int x, int y) {
/// return x + y;
/// }, 1);
/// // Run() only needs the remaining unbound argument |y|.
/// printf("1 + 2 = %d\n", std::move(cb).Run(2)); // Prints 3
/// printf("cb is null? %s\n",
/// cb.is_null() ? "true" : "false"); // Prints true
/// std::move(cb).Run(2); // Crashes since |cb| has already run.
/// </pre>
///
/// Callbacks also support cancellation. A common use is binding the receiver
/// object as a WeakPtr<T>. If that weak pointer is invalidated, calling Run()
/// will be a no-op. Note that |IsCancelled()| and |is_null()| are distinct:
/// simply cancelling a callback will not also make it null.
///
/// See https://chromium.googlesource.com/chromium/src/+/lkgr/docs/callback.md
/// for the full documentation.
#ifndef CEF_INCLUDE_BASE_CEF_CALLBACK_H_
#define CEF_INCLUDE_BASE_CEF_CALLBACK_H_

8
include/base/cef_callback_forward.h
View File

@ -48,9 +48,11 @@ class OnceCallback;
template <typename Signature>
class RepeatingCallback;
// Syntactic sugar to make OnceClosure<void()> and RepeatingClosure<void()>
// easier to declare since they will be used in a lot of APIs with delayed
// execution.
///
/// Syntactic sugar to make OnceClosure<void()> and RepeatingClosure<void()>
/// easier to declare since they will be used in a lot of APIs with delayed
/// execution.
///
using OnceClosure = OnceCallback<void()>;
using RepeatingClosure = RepeatingCallback<void()>;

83
include/base/cef_callback_helpers.h
View File

@ -75,24 +75,32 @@ struct IsOnceCallbackImpl<OnceCallback<R(Args...)>> : std::true_type {};
} // namespace internal
// IsBaseCallback<T>::value is true when T is any of the Closure or Callback
// family of types.
///
/// IsBaseCallback<T>::value is true when T is any of the Closure or Callback
/// family of types.
///
template <typename T>
using IsBaseCallback = internal::IsBaseCallbackImpl<std::decay_t<T>>;
// IsOnceCallback<T>::value is true when T is a OnceClosure or OnceCallback
// type.
///
/// IsOnceCallback<T>::value is true when T is a OnceClosure or OnceCallback
/// type.
///
template <typename T>
using IsOnceCallback = internal::IsOnceCallbackImpl<std::decay_t<T>>;
// SFINAE friendly enabler allowing to overload methods for both Repeating and
// OnceCallbacks.
//
// Usage:
// template <template <typename> class CallbackType,
// ... other template args ...,
// typename = EnableIfIsBaseCallback<CallbackType>>
// void DoStuff(CallbackType<...> cb, ...);
///
/// SFINAE friendly enabler allowing to overload methods for both Repeating and
/// OnceCallbacks.
///
/// Usage:
/// <pre>
/// template <template <typename> class CallbackType,
/// ... other template args ...,
/// typename = EnableIfIsBaseCallback<CallbackType>>
/// void DoStuff(CallbackType<...> cb, ...);
/// </pre>
///
template <template <typename> class CallbackType>
using EnableIfIsBaseCallback =
std::enable_if_t<IsBaseCallback<CallbackType<void()>>::value>;
@ -129,13 +137,16 @@ class OnceCallbackHolder final {
} // namespace internal
// Wraps the given OnceCallback into a RepeatingCallback that relays its
// invocation to the original OnceCallback on the first invocation. The
// following invocations are just ignored.
//
// Note that this deliberately subverts the Once/Repeating paradigm of Callbacks
// but helps ease the migration from old-style Callbacks. Avoid if possible; use
// if necessary for migration. TODO(tzik): Remove it. https://crbug.com/730593
///
/// Wraps the given OnceCallback into a RepeatingCallback that relays its
/// invocation to the original OnceCallback on the first invocation. The
/// following invocations are just ignored.
///
/// Note that this deliberately subverts the Once/Repeating paradigm of
/// Callbacks but helps ease the migration from old-style Callbacks. Avoid if
/// possible; use if necessary for migration.
///
// TODO(tzik): Remove it. https://crbug.com/730593
template <typename... Args>
RepeatingCallback<void(Args...)> AdaptCallbackForRepeating(
OnceCallback<void(Args...)> callback) {
@ -145,9 +156,11 @@ RepeatingCallback<void(Args...)> AdaptCallbackForRepeating(
/*ignore_extra_runs=*/true));
}
// Wraps the given OnceCallback and returns two OnceCallbacks with an identical
// signature. On first invokation of either returned callbacks, the original
// callback is invoked. Invoking the remaining callback results in a crash.
///
/// Wraps the given OnceCallback and returns two OnceCallbacks with an identical
/// signature. On first invokation of either returned callbacks, the original
/// callback is invoked. Invoking the remaining callback results in a crash.
///
template <typename... Args>
std::pair<OnceCallback<void(Args...)>, OnceCallback<void(Args...)>>
SplitOnceCallback(OnceCallback<void(Args...)> callback) {
@ -158,10 +171,12 @@ SplitOnceCallback(OnceCallback<void(Args...)> callback) {
return std::make_pair(wrapped_once, wrapped_once);
}
// ScopedClosureRunner is akin to std::unique_ptr<> for Closures. It ensures
// that the Closure is executed no matter how the current scope exits.
// If you are looking for "ScopedCallback", "CallbackRunner", or
// "CallbackScoper" this is the class you want.
///
/// ScopedClosureRunner is akin to std::unique_ptr<> for Closures. It ensures
/// that the Closure is executed no matter how the current scope exits.
/// If you are looking for "ScopedCallback", "CallbackRunner", or
/// "CallbackScoper" this is the class you want.
///
class ScopedClosureRunner {
public:
ScopedClosureRunner();
@ -189,7 +204,9 @@ class ScopedClosureRunner {
OnceClosure closure_;
};
// Creates a null callback.
///
/// Creates a null callback.
///
class NullCallback {
public:
template <typename R, typename... Args>
@ -202,7 +219,9 @@ class NullCallback {
}
};
// Creates a callback that does nothing when called.
///
/// Creates a callback that does nothing when called.
///
class DoNothing {
public:
template <typename... Args>
@ -225,9 +244,11 @@ class DoNothing {
}
};
// Useful for creating a Closure that will delete a pointer when invoked. Only
// use this when necessary. In most cases MessageLoop::DeleteSoon() is a better
// fit.
///
/// Useful for creating a Closure that will delete a pointer when invoked. Only
/// use this when necessary. In most cases MessageLoop::DeleteSoon() is a better
/// fit.
///
template <typename T>
void DeletePointer(T* obj) {
delete obj;

105
include/base/cef_callback_list.h
View File

@ -28,54 +28,57 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW:
//
// A container for a list of callbacks. Provides callers the ability to manually
// or automatically unregister callbacks at any time, including during callback
// notification.
//
// TYPICAL USAGE:
//
// class MyWidget {
// public:
// using CallbackList = base::RepeatingCallbackList<void(const Foo&)>;
//
// // Registers |cb| to be called whenever NotifyFoo() is executed.
// CallbackListSubscription RegisterCallback(CallbackList::CallbackType cb) {
// return callback_list_.Add(std::move(cb));
// }
//
// private:
// // Calls all registered callbacks, with |foo| as the supplied arg.
// void NotifyFoo(const Foo& foo) {
// callback_list_.Notify(foo);
// }
//
// CallbackList callback_list_;
// };
//
//
// class MyWidgetListener {
// private:
// void OnFoo(const Foo& foo) {
// // Called whenever MyWidget::NotifyFoo() is executed, unless
// // |foo_subscription_| has been destroyed.
// }
//
// // Automatically deregisters the callback when deleted (e.g. in
// // ~MyWidgetListener()). Unretained(this) is safe here since the
// // ScopedClosureRunner does not outlive |this|.
// CallbackListSubscription foo_subscription_ =
// MyWidget::Get()->RegisterCallback(
// base::BindRepeating(&MyWidgetListener::OnFoo,
// base::Unretained(this)));
// };
//
// UNSUPPORTED:
//
// * Destroying the CallbackList during callback notification.
//
// This is possible to support, but not currently necessary.
///
/// \file
/// A container for a list of callbacks. Provides callers the ability to
/// manually or automatically unregister callbacks at any time, including during
/// callback notification.
///
/// TYPICAL USAGE:
///
/// <pre>
/// class MyWidget {
/// public:
/// using CallbackList = base::RepeatingCallbackList<void(const Foo&)>;
///
/// // Registers |cb| to be called whenever NotifyFoo() is executed.
/// CallbackListSubscription RegisterCallback(CallbackList::CallbackType cb) {
/// return callback_list_.Add(std::move(cb));
/// }
///
/// private:
/// // Calls all registered callbacks, with |foo| as the supplied arg.
/// void NotifyFoo(const Foo& foo) {
/// callback_list_.Notify(foo);
/// }
///
/// CallbackList callback_list_;
/// };
///
///
/// class MyWidgetListener {
/// private:
/// void OnFoo(const Foo& foo) {
/// // Called whenever MyWidget::NotifyFoo() is executed, unless
/// // |foo_subscription_| has been destroyed.
/// }
///
/// // Automatically deregisters the callback when deleted (e.g. in
/// // ~MyWidgetListener()). Unretained(this) is safe here since the
/// // ScopedClosureRunner does not outlive |this|.
/// CallbackListSubscription foo_subscription_ =
/// MyWidget::Get()->RegisterCallback(
/// base::BindRepeating(&MyWidgetListener::OnFoo,
/// base::Unretained(this)));
/// };
/// </pre>
///
/// UNSUPPORTED:
///
/// * Destroying the CallbackList during callback notification.
///
/// This is possible to support, but not currently necessary.
///
#ifndef CEF_INCLUDE_BASE_CEF_CALLBACK_LIST_H_
#define CEF_INCLUDE_BASE_CEF_CALLBACK_LIST_H_
@ -381,9 +384,9 @@ class RepeatingCallbackList
}
};
// Syntactic sugar to parallel that used for Callbacks.
// ClosureList explicitly not provided since it is not used, and CallbackList
// is deprecated. {Once,Repeating}ClosureList should instead be used.
///
/// Syntactic sugar to parallel that used for Callbacks.
///
using OnceClosureList = OnceCallbackList<void()>;
using RepeatingClosureList = RepeatingCallbackList<void()>;

89
include/base/cef_cancelable_callback.h
View File

@ -28,44 +28,51 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// CancelableCallback is a wrapper around base::Callback that allows
// cancellation of a callback. CancelableCallback takes a reference on the
// wrapped callback until this object is destroyed or Reset()/Cancel() are
// called.
//
// NOTE:
//
// Calling CancelableCallback::Cancel() brings the object back to its natural,
// default-constructed state, i.e., CancelableCallback::callback() will return
// a null callback.
//
// THREAD-SAFETY:
//
// CancelableCallback objects must be created on, posted to, cancelled on, and
// destroyed on the same thread.
//
//
// EXAMPLE USAGE:
//
// In the following example, the test is verifying that RunIntensiveTest()
// Quit()s the message loop within 4 seconds. The cancelable callback is posted
// to the message loop, the intensive test runs, the message loop is run,
// then the callback is cancelled.
//
// RunLoop run_loop;
//
// void TimeoutCallback(const std::string& timeout_message) {
// FAIL() << timeout_message;
// run_loop.QuitWhenIdle();
// }
//
// CancelableOnceClosure timeout(
// base::BindOnce(&TimeoutCallback, "Test timed out."));
// ThreadTaskRunnerHandle::Get()->PostDelayedTask(FROM_HERE, timeout.callback(),
// TimeDelta::FromSeconds(4));
// RunIntensiveTest();
// run_loop.Run();
// timeout.Cancel(); // Hopefully this is hit before the timeout callback runs.
///
/// \file
/// CancelableCallback is a wrapper around base::Callback that allows
/// cancellation of a callback. CancelableCallback takes a reference on the
/// wrapped callback until this object is destroyed or Reset()/Cancel() are
/// called.
///
/// NOTE:
///
/// Calling CancelableCallback::Cancel() brings the object back to its natural,
/// default-constructed state, i.e., CancelableCallback::callback() will return
/// a null callback.
///
/// THREAD-SAFETY:
///
/// CancelableCallback objects must be created on, posted to, cancelled on, and
/// destroyed on the same thread.
///
///
/// EXAMPLE USAGE:
///
/// In the following example, the test is verifying that RunIntensiveTest()
/// Quit()s the message loop within 4 seconds. The cancelable callback is posted
/// to the message loop, the intensive test runs, the message loop is run,
/// then the callback is cancelled.
///
/// <pre>
/// RunLoop run_loop;
///
/// void TimeoutCallback(const std::string& timeout_message) {
/// FAIL() << timeout_message;
/// run_loop.QuitWhenIdle();
/// }
///
/// CancelableOnceClosure timeout(
/// base::BindOnce(&TimeoutCallback, "Test timed out."));
/// ThreadTaskRunnerHandle::Get()->PostDelayedTask(FROM_HERE,
/// timeout.callback(),
/// TimeDelta::FromSeconds(4));
/// RunIntensiveTest();
/// run_loop.Run();
/// // Hopefully this is hit before the timeout callback runs.
/// timeout.Cancel();
/// </pre>
///
#ifndef CEF_INCLUDE_BASE_CEF_CANCELABLE_CALLBACK_H_
#define CEF_INCLUDE_BASE_CEF_CANCELABLE_CALLBACK_H_
@ -166,8 +173,10 @@ class CancelableCallbackImpl {
} // namespace internal
// Consider using base::WeakPtr directly instead of base::CancelableCallback for
// the task cancellation.
///
/// Consider using base::WeakPtr directly instead of base::CancelableCallback
/// for the task cancellation.
///
template <typename Signature>
using CancelableOnceCallback =
internal::CancelableCallbackImpl<OnceCallback<Signature>>;

28
include/base/cef_lock.h
View File

@ -47,9 +47,11 @@
namespace base {
namespace cef_internal {
// A convenient wrapper for an OS specific critical section. The only real
// intelligence in this class is in debug mode for the support for the
// AssertAcquired() method.
///
/// A convenient wrapper for an OS specific critical section. The only real
/// intelligence in this class is in debug mode for the support for the
/// AssertAcquired() method.
///
class Lock {
public:
#if !DCHECK_IS_ON() // Optimized wrapper implementation
@ -62,10 +64,12 @@ class Lock {
void Acquire() { lock_.Lock(); }
void Release() { lock_.Unlock(); }
// If the lock is not held, take it and return true. If the lock is already
// held by another thread, immediately return false. This must not be called
// by a thread already holding the lock (what happens is undefined and an
// assertion may fail).
///
/// If the lock is not held, take it and return true. If the lock is already
/// held by another thread, immediately return false. This must not be called
/// by a thread already holding the lock (what happens is undefined and an
/// assertion may fail).
///
bool Try() { return lock_.Try(); }
// Null implementation if not debug.
@ -116,7 +120,9 @@ class Lock {
LockImpl lock_;
};
// A helper class that acquires the given Lock while the AutoLock is in scope.
///
/// A helper class that acquires the given Lock while the AutoLock is in scope.
///
class AutoLock {
public:
struct AlreadyAcquired {};
@ -139,8 +145,10 @@ class AutoLock {
Lock& lock_;
};
// AutoUnlock is a helper that will Release() the |lock| argument in the
// constructor, and re-Acquire() it in the destructor.
///
/// AutoUnlock is a helper that will Release() the |lock| argument in the
/// constructor, and re-Acquire() it in the destructor.
///
class AutoUnlock {
public:
explicit AutoUnlock(Lock& lock) : lock_(lock) {

228
include/base/cef_logging.h
View File

@ -27,110 +27,130 @@
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// ---------------------------------------------------------------------------
//
// The contents of this file are only available to applications that link
// against the libcef_dll_wrapper target.
//
// WARNING: Logging macros should not be used in the main/browser process before
// calling CefInitialize or in sub-processes before calling CefExecuteProcess.
//
// Instructions
// ------------
//
// Make a bunch of macros for logging. The way to log things is to stream
// things to LOG(<a particular severity level>). E.g.,
//
// LOG(INFO) << "Found " << num_cookies << " cookies";
//
// You can also do conditional logging:
//
// LOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
//
// The CHECK(condition) macro is active in both debug and release builds and
// effectively performs a LOG(FATAL) which terminates the process and
// generates a crashdump unless a debugger is attached.
//
// There are also "debug mode" logging macros like the ones above:
//
// DLOG(INFO) << "Found cookies";
//
// DLOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
//
// All "debug mode" logging is compiled away to nothing for non-debug mode
// compiles. LOG_IF and development flags also work well together
// because the code can be compiled away sometimes.
//
// We also have
//
// LOG_ASSERT(assertion);
// DLOG_ASSERT(assertion);
//
// which is syntactic sugar for {,D}LOG_IF(FATAL, assert fails) << assertion;
//
// There are "verbose level" logging macros. They look like
//
// VLOG(1) << "I'm printed when you run the program with --v=1 or more";
// VLOG(2) << "I'm printed when you run the program with --v=2 or more";
//
// These always log at the INFO log level (when they log at all).
// The verbose logging can also be turned on module-by-module. For instance,
// --vmodule=profile=2,icon_loader=1,browser_*=3,*/chromeos/*=4 --v=0
// will cause:
// a. VLOG(2) and lower messages to be printed from profile.{h,cc}
// b. VLOG(1) and lower messages to be printed from icon_loader.{h,cc}
// c. VLOG(3) and lower messages to be printed from files prefixed with
// "browser"
// d. VLOG(4) and lower messages to be printed from files under a
// "chromeos" directory.
// e. VLOG(0) and lower messages to be printed from elsewhere
//
// The wildcarding functionality shown by (c) supports both '*' (match
// 0 or more characters) and '?' (match any single character)
// wildcards. Any pattern containing a forward or backward slash will
// be tested against the whole pathname and not just the module.
// E.g., "*/foo/bar/*=2" would change the logging level for all code
// in source files under a "foo/bar" directory.
//
// There's also VLOG_IS_ON(n) "verbose level" condition macro. To be used as
//
// if (VLOG_IS_ON(2)) {
// // do some logging preparation and logging
// // that can't be accomplished with just VLOG(2) << ...;
// }
//
// There is also a VLOG_IF "verbose level" condition macro for sample
// cases, when some extra computation and preparation for logs is not
// needed.
//
// VLOG_IF(1, (size > 1024))
// << "I'm printed when size is more than 1024 and when you run the "
// "program with --v=1 or more";
//
// We also override the standard 'assert' to use 'DLOG_ASSERT'.
//
// Lastly, there is:
//
// PLOG(ERROR) << "Couldn't do foo";
// DPLOG(ERROR) << "Couldn't do foo";
// PLOG_IF(ERROR, cond) << "Couldn't do foo";
// DPLOG_IF(ERROR, cond) << "Couldn't do foo";
// PCHECK(condition) << "Couldn't do foo";
// DPCHECK(condition) << "Couldn't do foo";
//
// which append the last system error to the message in string form (taken from
// GetLastError() on Windows and errno on POSIX).
//
// The supported severity levels for macros that allow you to specify one
// are (in increasing order of severity) INFO, WARNING, ERROR, and FATAL.
//
// Very important: logging a message at the FATAL severity level causes
// the program to terminate (after the message is logged).
//
// There is the special severity of DFATAL, which logs FATAL in debug mode,
// ERROR in normal mode.
//
///
/// \file
/// A bunch of macros for logging.
///
/// NOTE: The contents of this file are only available to applications that link
/// against the libcef_dll_wrapper target.
///
/// WARNING: Logging macros should not be used in the main/browser process
/// before calling CefInitialize or in sub-processes before calling
/// CefExecuteProcess.
///
/// INSTRUCTIONS:
///
/// The way to log things is to stream things to LOG(<a particular severity
/// level>). E.g.,
///
/// <pre>
/// LOG(INFO) << "Found " << num_cookies << " cookies";
/// </pre>
///
/// You can also do conditional logging:
///
/// <pre>
/// LOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
/// </pre>
///
/// The CHECK(condition) macro is active in both debug and release builds and
/// effectively performs a LOG(FATAL) which terminates the process and
/// generates a crashdump unless a debugger is attached.
///
/// There are also "debug mode" logging macros like the ones above:
///
/// <pre>
/// DLOG(INFO) << "Found cookies";
///
/// DLOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
/// </pre>
///
/// All "debug mode" logging is compiled away to nothing for non-debug mode
/// compiles. LOG_IF and development flags also work well together
/// because the code can be compiled away sometimes.
///
/// We also have
///
/// <pre>
/// LOG_ASSERT(assertion);
/// DLOG_ASSERT(assertion);
/// </pre>
///
/// which is syntactic sugar for "{,D}LOG_IF(FATAL, assert fails) << assertion;"
///
/// There are "verbose level" logging macros. They look like
///
/// <pre>
/// VLOG(1) << "I'm printed when you run the program with --v=1 or more";
/// VLOG(2) << "I'm printed when you run the program with --v=2 or more";
/// </pre>
///
/// These always log at the INFO log level (when they log at all).
/// The verbose logging can also be turned on module-by-module. For instance,
/// <pre>
/// --vmodule=profile=2,icon_loader=1,browser_*=3,*/chromeos/*=4 --v=0
/// </pre>
/// will cause:
/// 1. VLOG(2) and lower messages to be printed from profile.{h,cc}
/// 2. VLOG(1) and lower messages to be printed from icon_loader.{h,cc}
/// 3. VLOG(3) and lower messages to be printed from files prefixed with
/// "browser"
/// 4. VLOG(4) and lower messages to be printed from files under a
/// "chromeos" directory.
/// 5. VLOG(0) and lower messages to be printed from elsewhere
///
/// The wildcarding functionality shown by (c) supports both '*' (match
/// 0 or more characters) and '?' (match any single character)
/// wildcards. Any pattern containing a forward or backward slash will
/// be tested against the whole pathname and not just the module.
/// E.g., "*/foo/bar/*=2" would change the logging level for all code
/// in source files under a "foo/bar" directory.
///
/// There's also VLOG_IS_ON(n) "verbose level" condition macro. To be used as
///
/// <pre>
/// if (VLOG_IS_ON(2)) {
/// // do some logging preparation and logging
/// // that can't be accomplished with just VLOG(2) << ...;
/// }
/// </pre>
///
/// There is also a VLOG_IF "verbose level" condition macro for sample
/// cases, when some extra computation and preparation for logs is not
/// needed.
///
/// <pre>
/// VLOG_IF(1, (size > 1024))
/// << "I'm printed when size is more than 1024 and when you run the "
/// "program with --v=1 or more";
/// </pre>
///
/// We also override the standard 'assert' to use 'DLOG_ASSERT'.
///
/// Lastly, there is:
///
/// <pre>
/// PLOG(ERROR) << "Couldn't do foo";
/// DPLOG(ERROR) << "Couldn't do foo";
/// PLOG_IF(ERROR, cond) << "Couldn't do foo";
/// DPLOG_IF(ERROR, cond) << "Couldn't do foo";
/// PCHECK(condition) << "Couldn't do foo";
/// DPCHECK(condition) << "Couldn't do foo";
/// </pre>
///
/// which append the last system error to the message in string form (taken from
/// GetLastError() on Windows and errno on POSIX).
///
/// The supported severity levels for macros that allow you to specify one
/// are (in increasing order of severity) INFO, WARNING, ERROR, and FATAL.
///
/// Very important: logging a message at the FATAL severity level causes
/// the program to terminate (after the message is logged).
///
/// There is the special severity of DFATAL, which logs FATAL in debug mode,
/// ERROR in normal mode.
///
#ifndef CEF_INCLUDE_BASE_CEF_LOGGING_H_
#define CEF_INCLUDE_BASE_CEF_LOGGING_H_

4
include/base/cef_macros.h
View File

@ -38,8 +38,8 @@
// updated to match.
// ALL DISALLOW_xxx MACROS ARE DEPRECATED; DO NOT USE IN NEW CODE.
// Use explicit deletions instead. See the section on copyability/movability in
// //styleguide/c++/c++-dos-and-donts.md for more information.
// Use explicit deletions instead. For more information see
// https://chromium.googlesource.com/chromium/src/+/lkgr/styleguide/c++/c++-dos-and-donts.md#explicitly-declare-class-copyability_movability
// DEPRECATED: See above. Makes a class uncopyable.
#define DISALLOW_COPY(TypeName) TypeName(const TypeName&) = delete

40
include/base/cef_platform_thread.h
View File

@ -49,17 +49,21 @@
namespace base {
// Used for logging. Always an integer value.
///
/// Used for logging. Always an integer value.
///
typedef cef_platform_thread_id_t PlatformThreadId;
// Used for thread checking and debugging.
// Meant to be as fast as possible.
// These are produced by PlatformThread::CurrentRef(), and used to later
// check if we are on the same thread or not by using ==. These are safe
// to copy between threads, but can't be copied to another process as they
// have no meaning there. Also, the internal identifier can be re-used
// after a thread dies, so a PlatformThreadRef cannot be reliably used
// to distinguish a new thread from an old, dead thread.
///
/// Used for thread checking and debugging.
/// Meant to be as fast as possible.
/// These are produced by PlatformThread::CurrentRef(), and used to later
/// check if we are on the same thread or not by using ==. These are safe
/// to copy between threads, but can't be copied to another process as they
/// have no meaning there. Also, the internal identifier can be re-used
/// after a thread dies, so a PlatformThreadRef cannot be reliably used
/// to distinguish a new thread from an old, dead thread.
///
class PlatformThreadRef {
public:
typedef cef_platform_thread_handle_t RefType;
@ -76,18 +80,24 @@ class PlatformThreadRef {
RefType id_;
};
// A namespace for low-level thread functions.
// Chromium uses a class with static methods but CEF uses an actual namespace
// to avoid linker problems with the sandbox libaries on Windows.
///
/// A namespace for low-level thread functions.
/// Chromium uses a class with static methods but CEF uses an actual namespace
/// to avoid linker problems with the sandbox libaries on Windows.
///
namespace PlatformThread {
// Gets the current thread id, which may be useful for logging purposes.
///
/// Gets the current thread id, which may be useful for logging purposes.
///
inline PlatformThreadId CurrentId() {
return cef_get_current_platform_thread_id();
}
// Gets the current thread reference, which can be used to check if
// we're on the right thread quickly.
///
/// Gets the current thread reference, which can be used to check if
/// we're on the right thread quickly.
///
inline PlatformThreadRef CurrentRef() {
return PlatformThreadRef(cef_get_current_platform_thread_handle());
}

8
include/base/cef_ptr_util.h
View File

@ -45,9 +45,11 @@
namespace base {
// Helper to transfer ownership of a raw pointer to a std::unique_ptr<T>.
// Note that std::unique_ptr<T> has very different semantics from
// std::unique_ptr<T[]>: do not use this helper for array allocations.
///
/// Helper to transfer ownership of a raw pointer to a std::unique_ptr<T>.
/// Note that std::unique_ptr<T> has very different semantics from
/// std::unique_ptr<T[]>: do not use this helper for array allocations.
///
template <typename T>
std::unique_ptr<T> WrapUnique(T* ptr) {
return std::unique_ptr<T>(ptr);

147
include/base/cef_ref_counted.h
View File

@ -290,52 +290,26 @@ class ScopedAllowCrossThreadRefCountAccess final {
using ScopedAllowCrossThreadRefCountAccess =
cef_subtle::ScopedAllowCrossThreadRefCountAccess;
//
// A base class for reference counted classes. Otherwise, known as a cheap
// knock-off of WebKit's RefCounted<T> class. To use this, just extend your
// class from it like so:
//
// class MyFoo : public base::RefCounted<MyFoo> {
// ...
// private:
// friend class base::RefCounted<MyFoo>;
// ~MyFoo();
// };
//
// Usage Notes:
// 1. You should always make your destructor non-public, to avoid any code
// deleting the object accidentally while there are references to it.
// 2. You should always make the ref-counted base class a friend of your class,
// so that it can access the destructor.
//
// The ref count manipulation to RefCounted is NOT thread safe and has DCHECKs
// to trap unsafe cross thread usage. A subclass instance of RefCounted can be
// passed to another execution thread only when its ref count is 1. If the ref
// count is more than 1, the RefCounted class verifies the ref updates are made
// on the same execution thread as the previous ones. The subclass can also
// manually call IsOnValidThread to trap other non-thread-safe accesses; see
// the documentation for that method.
//
//
// The reference count starts from zero by default, and we intended to migrate
// to start-from-one ref count. Put REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() to
// the ref counted class to opt-in.
//
// If an object has start-from-one ref count, the first scoped_refptr need to be
// created by base::AdoptRef() or base::MakeRefCounted(). We can use
// base::MakeRefCounted() to create create both type of ref counted object.
//
// The motivations to use start-from-one ref count are:
// - Start-from-one ref count doesn't need the ref count increment for the
// first reference.
// - It can detect an invalid object acquisition for a being-deleted object
// that has zero ref count. That tends to happen on custom deleter that
// delays the deletion.
// TODO(tzik): Implement invalid acquisition detection.
// - Behavior parity to Blink's WTF::RefCounted, whose count starts from one.
// And start-from-one ref count is a step to merge WTF::RefCounted into
// base::RefCounted.
//
///
/// The reference count starts from zero by default, and we intended to migrate
/// to start-from-one ref count. Put REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() to
/// the ref counted class to opt-in.
///
/// If an object has start-from-one ref count, the first scoped_refptr need to
/// be created by base::AdoptRef() or base::MakeRefCounted(). We can use
/// base::MakeRefCounted() to create create both type of ref counted object.
///
/// The motivations to use start-from-one ref count are:
/// - Start-from-one ref count doesn't need the ref count increment for the
/// first reference.
/// - It can detect an invalid object acquisition for a being-deleted object
/// that has zero ref count. That tends to happen on custom deleter that
/// delays the deletion.
/// TODO(tzik): Implement invalid acquisition detection.
/// - Behavior parity to Blink's WTF::RefCounted, whose count starts from one.
/// And start-from-one ref count is a step to merge WTF::RefCounted into
/// base::RefCounted.
///
#define REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() \
static constexpr ::base::cef_subtle::StartRefCountFromOneTag \
kRefCountPreference = ::base::cef_subtle::kStartRefCountFromOneTag
@ -343,6 +317,10 @@ using ScopedAllowCrossThreadRefCountAccess =
template <class T, typename Traits>
class RefCounted;
///
/// Default traits for RefCounted<T>. Deletes the object when its ref count
/// reaches 0. Overload to delete it on a different thread etc.
///
template <typename T>
struct DefaultRefCountedTraits {
static void Destruct(const T* x) {
@ -350,6 +328,34 @@ struct DefaultRefCountedTraits {
}
};
///
/// A base class for reference counted classes. Otherwise, known as a cheap
/// knock-off of WebKit's RefCounted<T> class. To use this, just extend your
/// class from it like so:
///
/// <pre>
/// class MyFoo : public base::RefCounted<MyFoo> {
/// ...
/// private:
/// friend class base::RefCounted<MyFoo>;
/// ~MyFoo();
/// };
/// </pre>
///
/// Usage Notes:
/// 1. You should always make your destructor non-public, to avoid any code
/// deleting the object accidentally while there are references to it.
/// 2. You should always make the ref-counted base class a friend of your class,
/// so that it can access the destructor.
///
/// The ref count manipulation to RefCounted is NOT thread safe and has DCHECKs
/// to trap unsafe cross thread usage. A subclass instance of RefCounted can be
/// passed to another execution thread only when its ref count is 1. If the ref
/// count is more than 1, the RefCounted class verifies the ref updates are made
/// on the same execution thread as the previous ones. The subclass can also
/// manually call IsOnValidThread to trap other non-thread-safe accesses; see
/// the documentation for that method.
///
template <class T, typename Traits = DefaultRefCountedTraits<T>>
class RefCounted : public cef_subtle::RefCountedBase {
public:
@ -389,8 +395,10 @@ class RefCounted : public cef_subtle::RefCountedBase {
template <class T, typename Traits>
class RefCountedThreadSafe;
// Default traits for RefCountedThreadSafe<T>. Deletes the object when its ref
// count reaches 0. Overload to delete it on a different thread etc.
///
/// Default traits for RefCountedThreadSafe<T>. Deletes the object when its ref
/// count reaches 0. Overload to delete it on a different thread etc.
///
template <typename T>
struct DefaultRefCountedThreadSafeTraits {
static void Destruct(const T* x) {
@ -402,21 +410,26 @@ struct DefaultRefCountedThreadSafeTraits {
}
};
//
// A thread-safe variant of RefCounted<T>
//
// class MyFoo : public base::RefCountedThreadSafe<MyFoo> {
// ...
// };
//
// If you're using the default trait, then you should add compile time
// asserts that no one else is deleting your object. i.e.
// private:
// friend class base::RefCountedThreadSafe<MyFoo>;
// ~MyFoo();
//
// We can use REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() with RefCountedThreadSafe
// too. See the comment above the RefCounted definition for details.
///
/// A thread-safe variant of RefCounted<T>
///
/// <pre>
/// class MyFoo : public base::RefCountedThreadSafe<MyFoo> {
/// ...
/// };
/// </pre>
///
/// If you're using the default trait, then you should add compile time
/// asserts that no one else is deleting your object. i.e.
/// <pre>
/// private:
/// friend class base::RefCountedThreadSafe<MyFoo>;
/// ~MyFoo();
/// </pre>
///
/// We can use REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() with RefCountedThreadSafe
/// too. See the comment above the RefCounted definition for details.
///
template <class T, typename Traits = DefaultRefCountedThreadSafeTraits<T>>
class RefCountedThreadSafe : public cef_subtle::RefCountedThreadSafeBase {
public:
@ -457,10 +470,10 @@ class RefCountedThreadSafe : public cef_subtle::RefCountedThreadSafeBase {
}
};
//
// A thread-safe wrapper for some piece of data so we can place other
// things in scoped_refptrs<>.
//
///
/// A thread-safe wrapper for some piece of data so we can place other
/// things in scoped_refptrs<>.
///
template <typename T>
class RefCountedData
: public base::RefCountedThreadSafe<base::RefCountedData<T>> {

132
include/base/cef_scoped_refptr.h
View File

@ -142,68 +142,76 @@ scoped_refptr<T> WrapRefCounted(T* t) {
} // namespace base
//
// A smart pointer class for reference counted objects. Use this class instead
// of calling AddRef and Release manually on a reference counted object to
// avoid common memory leaks caused by forgetting to Release an object
// reference. Sample usage:
//
// class MyFoo : public RefCounted<MyFoo> {
// ...
// private:
// friend class RefCounted<MyFoo>; // Allow destruction by RefCounted<>.
// ~MyFoo(); // Destructor must be private/protected.
// };
//
// void some_function() {
// scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
// foo->Method(param);
// // |foo| is released when this function returns
// }
//
// void some_other_function() {
// scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
// ...
// foo.reset(); // explicitly releases |foo|
// ...
// if (foo)
// foo->Method(param);
// }
//
// The above examples show how scoped_refptr<T> acts like a pointer to T.
// Given two scoped_refptr<T> classes, it is also possible to exchange
// references between the two objects, like so:
//
// {
// scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
// scoped_refptr<MyFoo> b;
//
// b.swap(a);
// // now, |b| references the MyFoo object, and |a| references nullptr.
// }
//
// To make both |a| and |b| in the above example reference the same MyFoo
// object, simply use the assignment operator:
//
// {
// scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
// scoped_refptr<MyFoo> b;
//
// b = a;
// // now, |a| and |b| each own a reference to the same MyFoo object.
// }
//
// Also see Chromium's ownership and calling conventions:
// https://chromium.googlesource.com/chromium/src/+/lkgr/styleguide/c++/c++.md#object-ownership-and-calling-conventions
// Specifically:
// If the function (at least sometimes) takes a ref on a refcounted object,
// declare the param as scoped_refptr<T>. The caller can decide whether it
// wishes to transfer ownership (by calling std::move(t) when passing t) or
// retain its ref (by simply passing t directly).
// In other words, use scoped_refptr like you would a std::unique_ptr except
// in the odd case where it's required to hold on to a ref while handing one
// to another component (if a component merely needs to use t on the stack
// without keeping a ref: pass t as a raw T*).
///
/// A smart pointer class for reference counted objects. Use this class instead
/// of calling AddRef and Release manually on a reference counted object to
/// avoid common memory leaks caused by forgetting to Release an object
/// reference. Sample usage:
///
/// <pre>
/// class MyFoo : public RefCounted<MyFoo> {
/// ...
/// private:
/// friend class RefCounted<MyFoo>; // Allow destruction by RefCounted<>.
/// ~MyFoo(); // Destructor must be
/// private/protected.
/// };
///
/// void some_function() {
/// scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
/// foo->Method(param);
/// // |foo| is released when this function returns
/// }
///
/// void some_other_function() {
/// scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
/// ...
/// foo.reset(); // explicitly releases |foo|
/// ...
/// if (foo)
/// foo->Method(param);
/// }
/// </pre>
///
/// The above examples show how scoped_refptr<T> acts like a pointer to T.
/// Given two scoped_refptr<T> classes, it is also possible to exchange
/// references between the two objects, like so:
///
/// <pre>
/// {
/// scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
/// scoped_refptr<MyFoo> b;
///
/// b.swap(a);
/// // now, |b| references the MyFoo object, and |a| references nullptr.
/// }
/// </pre>
///
/// To make both |a| and |b| in the above example reference the same MyFoo
/// object, simply use the assignment operator:
///
/// <pre>
/// {
/// scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
/// scoped_refptr<MyFoo> b;
///
/// b = a;
/// // now, |a| and |b| each own a reference to the same MyFoo object.
/// }
/// </pre>
///
/// Also see Chromium's ownership and calling conventions:
/// https://chromium.googlesource.com/chromium/src/+/lkgr/styleguide/c++/c++.md#object-ownership-and-calling-conventions
/// Specifically:
/// If the function (at least sometimes) takes a ref on a refcounted object,
/// declare the param as scoped_refptr<T>. The caller can decide whether it
/// wishes to transfer ownership (by calling std::move(t) when passing t) or
/// retain its ref (by simply passing t directly).
/// In other words, use scoped_refptr like you would a std::unique_ptr except
/// in the odd case where it's required to hold on to a ref while handing one
/// to another component (if a component merely needs to use t on the stack
/// without keeping a ref: pass t as a raw T*).
///
template <class T>
class TRIVIAL_ABI scoped_refptr {
public:

74
include/base/cef_scoped_typeref_mac.h
View File

@ -28,40 +28,6 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// ScopedTypeRef<> is patterned after std::unique_ptr<>, but maintains ownership
// of a reference to any type that is maintained by Retain and Release methods.
//
// The Traits structure must provide the Retain and Release methods for type T.
// A default ScopedTypeRefTraits is used but not defined, and should be defined
// for each type to use this interface. For example, an appropriate definition
// of ScopedTypeRefTraits for CGLContextObj would be:
//
// template<>
// struct ScopedTypeRefTraits<CGLContextObj> {
// static CGLContextObj InvalidValue() { return nullptr; }
// static CGLContextObj Retain(CGLContextObj object) {
// CGLContextRetain(object);
// return object;
// }
// static void Release(CGLContextObj object) { CGLContextRelease(object); }
// };
//
// For the many types that have pass-by-pointer create functions, the function
// InitializeInto() is provided to allow direct initialization and assumption
// of ownership of the object. For example, continuing to use the above
// CGLContextObj specialization:
//
// base::ScopedTypeRef<CGLContextObj> context;
// CGLCreateContext(pixel_format, share_group, context.InitializeInto());
//
// For initialization with an existing object, the caller may specify whether
// the ScopedTypeRef<> being initialized is assuming the caller's existing
// ownership of the object (and should not call Retain in initialization) or if
// it should not assume this ownership and must create its own (by calling
// Retain in initialization). This behavior is based on the |policy| parameter,
// with |ASSUME| for the former and |RETAIN| for the latter. The default policy
// is to |ASSUME|.
#ifndef CEF_INCLUDE_BASE_CEF_SCOPED_TYPEREF_MAC_H_
#define CEF_INCLUDE_BASE_CEF_SCOPED_TYPEREF_MAC_H_
#pragma once
@ -82,6 +48,46 @@ namespace base {
template <typename T>
struct ScopedTypeRefTraits;
///
/// ScopedTypeRef<> is patterned after std::unique_ptr<>, but maintains
/// ownership of a reference to any type that is maintained by Retain and
/// Release methods.
///
/// The Traits structure must provide the Retain and Release methods for type T.
/// A default ScopedTypeRefTraits is used but not defined, and should be defined
/// for each type to use this interface. For example, an appropriate definition
/// of ScopedTypeRefTraits for CGLContextObj would be:
///
/// <pre>
/// template<>
/// struct ScopedTypeRefTraits<CGLContextObj> {
/// static CGLContextObj InvalidValue() { return nullptr; }
/// static CGLContextObj Retain(CGLContextObj object) {
/// CGLContextRetain(object);
/// return object;
/// }
/// static void Release(CGLContextObj object) { CGLContextRelease(object); }
/// };
/// </pre>
///
/// For the many types that have pass-by-pointer create functions, the function
/// InitializeInto() is provided to allow direct initialization and assumption
/// of ownership of the object. For example, continuing to use the above
/// CGLContextObj specialization:
///
/// <pre>
/// base::ScopedTypeRef<CGLContextObj> context;
/// CGLCreateContext(pixel_format, share_group, context.InitializeInto());
/// </pre>
///
/// For initialization with an existing object, the caller may specify whether
/// the ScopedTypeRef<> being initialized is assuming the caller's existing
/// ownership of the object (and should not call Retain in initialization) or if
/// it should not assume this ownership and must create its own (by calling
/// Retain in initialization). This behavior is based on the |policy| parameter,
/// with |ASSUME| for the former and |RETAIN| for the latter. The default policy
/// is to |ASSUME|.
///
template <typename T, typename Traits = ScopedTypeRefTraits<T>>
class ScopedTypeRef {
public:

87
include/base/cef_thread_checker.h
View File

@ -43,10 +43,12 @@
#include "include/base/cef_logging.h"
#include "include/base/internal/cef_thread_checker_impl.h"
// Apart from debug builds, we also enable the thread checker in
// builds with DCHECK_ALWAYS_ON so that trybots and waterfall bots
// with this define will get the same level of thread checking as
// debug bots.
///
/// Apart from debug builds, we also enable the thread checker in
/// builds with DCHECK_ALWAYS_ON so that trybots and waterfall bots
/// with this define will get the same level of thread checking as
/// debug bots.
///
#if DCHECK_IS_ON()
#define ENABLE_THREAD_CHECKER 1
#else
@ -57,10 +59,12 @@ namespace base {
namespace cef_internal {
// Do nothing implementation, for use in release mode.
//
// Note: You should almost always use the ThreadChecker class to get the
// right version for your build configuration.
///
/// Do nothing implementation, for use in release mode.
///
/// Note: You should almost always use the ThreadChecker class to get the
/// right version for your build configuration.
///
class ThreadCheckerDoNothing {
public:
bool CalledOnValidThread() const { return true; }
@ -70,37 +74,42 @@ class ThreadCheckerDoNothing {
} // namespace cef_internal
// ThreadChecker is a helper class used to help verify that some methods of a
// class are called from the same thread. It provides identical functionality to
// base::NonThreadSafe, but it is meant to be held as a member variable, rather
// than inherited from base::NonThreadSafe.
//
// While inheriting from base::NonThreadSafe may give a clear indication about
// the thread-safety of a class, it may also lead to violations of the style
// guide with regard to multiple inheritance. The choice between having a
// ThreadChecker member and inheriting from base::NonThreadSafe should be based
// on whether:
// - Derived classes need to know the thread they belong to, as opposed to
// having that functionality fully encapsulated in the base class.
// - Derived classes should be able to reassign the base class to another
// thread, via DetachFromThread.
//
// If neither of these are true, then having a ThreadChecker member and calling
// CalledOnValidThread is the preferable solution.
//
// Example:
// class MyClass {
// public:
// void Foo() {
// DCHECK(thread_checker_.CalledOnValidThread());
// ... (do stuff) ...
// }
//
// private:
// ThreadChecker thread_checker_;
// }
//
// In Release mode, CalledOnValidThread will always return true.
///
/// ThreadChecker is a helper class used to help verify that some methods of a
/// class are called from the same thread. It provides identical functionality
/// to base::NonThreadSafe, but it is meant to be held as a member variable,
/// rather than inherited from base::NonThreadSafe.
///
/// While inheriting from base::NonThreadSafe may give a clear indication about
/// the thread-safety of a class, it may also lead to violations of the style
/// guide with regard to multiple inheritance. The choice between having a
/// ThreadChecker member and inheriting from base::NonThreadSafe should be based
/// on whether:
/// - Derived classes need to know the thread they belong to, as opposed to
/// having that functionality fully encapsulated in the base class.
/// - Derived classes should be able to reassign the base class to another
/// thread, via DetachFromThread.
///
/// If neither of these are true, then having a ThreadChecker member and calling
/// CalledOnValidThread is the preferable solution.
///
/// Example:
///
/// <pre>
/// class MyClass {
/// public:
/// void Foo() {
/// DCHECK(thread_checker_.CalledOnValidThread());
/// ... (do stuff) ...
/// }
///
/// private:
/// ThreadChecker thread_checker_;
/// }
/// </pre>
///
/// In Release mode, CalledOnValidThread will always return true.
///
#if ENABLE_THREAD_CHECKER
class ThreadChecker : public cef_internal::ThreadCheckerImpl {};
#else

414
include/base/cef_trace_event.h
View File

@ -29,111 +29,133 @@
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
///
// Trace events are for tracking application performance and resource usage.
// Macros are provided to track:
// Begin and end of function calls
// Counters
//
// Events are issued against categories. Whereas LOG's categories are statically
// defined, TRACE categories are created implicitly with a string. For example:
// TRACE_EVENT_INSTANT0("MY_SUBSYSTEM", "SomeImportantEvent")
//
// Events can be INSTANT, or can be pairs of BEGIN and END in the same scope:
// TRACE_EVENT_BEGIN0("MY_SUBSYSTEM", "SomethingCostly")
// doSomethingCostly()
// TRACE_EVENT_END0("MY_SUBSYSTEM", "SomethingCostly")
// Note: Our tools can't always determine the correct BEGIN/END pairs unless
// these are used in the same scope. Use ASYNC_BEGIN/ASYNC_END macros if you
// need them to be in separate scopes.
//
// A common use case is to trace entire function scopes. This issues a trace
// BEGIN and END automatically:
// void doSomethingCostly() {
// TRACE_EVENT0("MY_SUBSYSTEM", "doSomethingCostly");
// ...
// }
//
// Additional parameters can be associated with an event:
// void doSomethingCostly2(int howMuch) {
// TRACE_EVENT1("MY_SUBSYSTEM", "doSomethingCostly",
// "howMuch", howMuch);
// ...
// }
//
// The trace system will automatically add to this information the current
// process id, thread id, and a timestamp in microseconds.
//
// To trace an asynchronous procedure such as an IPC send/receive, use
// ASYNC_BEGIN and ASYNC_END:
// [single threaded sender code]
// static int send_count = 0;
// ++send_count;
// TRACE_EVENT_ASYNC_BEGIN0("ipc", "message", send_count);
// Send(new MyMessage(send_count));
// [receive code]
// void OnMyMessage(send_count) {
// TRACE_EVENT_ASYNC_END0("ipc", "message", send_count);
// }
// The third parameter is a unique ID to match ASYNC_BEGIN/ASYNC_END pairs.
// ASYNC_BEGIN and ASYNC_END can occur on any thread of any traced process.
// Pointers can be used for the ID parameter, and they will be mangled
// internally so that the same pointer on two different processes will not
// match. For example:
// class MyTracedClass {
// public:
// MyTracedClass() {
// TRACE_EVENT_ASYNC_BEGIN0("category", "MyTracedClass", this);
// }
// ~MyTracedClass() {
// TRACE_EVENT_ASYNC_END0("category", "MyTracedClass", this);
// }
// }
//
// The trace event also supports counters, which is a way to track a quantity
// as it varies over time. Counters are created with the following macro:
// TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter", g_myCounterValue);
//
// Counters are process-specific. The macro itself can be issued from any
// thread, however.
//
// Sometimes, you want to track two counters at once. You can do this with two
// counter macros:
// TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter0", g_myCounterValue[0]);
// TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter1", g_myCounterValue[1]);
// Or you can do it with a combined macro:
// TRACE_COUNTER2("MY_SUBSYSTEM", "myCounter",
// "bytesPinned", g_myCounterValue[0],
// "bytesAllocated", g_myCounterValue[1]);
// This indicates to the tracing UI that these counters should be displayed
// in a single graph, as a summed area chart.
//
// Since counters are in a global namespace, you may want to disembiguate with a
// unique ID, by using the TRACE_COUNTER_ID* variations.
//
// By default, trace collection is compiled in, but turned off at runtime.
// Collecting trace data is the responsibility of the embedding application. In
// CEF's case, calling BeginTracing will turn on tracing on all active
// processes.
//
//
// Memory scoping note:
// Tracing copies the pointers, not the string content, of the strings passed
// in for category, name, and arg_names. Thus, the following code will cause
// problems:
// char* str = strdup("impprtantName");
// TRACE_EVENT_INSTANT0("SUBSYSTEM", str); // BAD!
// free(str); // Trace system now has dangling pointer
//
// To avoid this issue with the |name| and |arg_name| parameters, use the
// TRACE_EVENT_COPY_XXX overloads of the macros at additional runtime
// overhead.
// Notes: The category must always be in a long-lived char* (i.e. static const).
// The |arg_values|, when used, are always deep copied with the _COPY
// macros.
//
//
// Thread Safety:
// All macros are thread safe and can be used from any process.
/// \file
/// Trace events are for tracking application performance and resource usage.
/// Macros are provided to track:
/// Begin and end of function calls
/// Counters
///
/// Events are issued against categories. Whereas LOG's categories are
/// statically defined, TRACE categories are created implicitly with a string.
/// For example: <pre>
/// TRACE_EVENT_INSTANT0("MY_SUBSYSTEM", "SomeImportantEvent")
/// </pre>
///
/// Events can be INSTANT, or can be pairs of BEGIN and END in the same scope:
/// <pre>
/// TRACE_EVENT_BEGIN0("MY_SUBSYSTEM", "SomethingCostly")
/// doSomethingCostly()
/// TRACE_EVENT_END0("MY_SUBSYSTEM", "SomethingCostly")
/// </pre>
/// Note: Our tools can't always determine the correct BEGIN/END pairs unless
/// these are used in the same scope. Use ASYNC_BEGIN/ASYNC_END macros if you
/// need them to be in separate scopes.
///
/// A common use case is to trace entire function scopes. This issues a trace
/// BEGIN and END automatically:
/// <pre>
/// void doSomethingCostly() {
/// TRACE_EVENT0("MY_SUBSYSTEM", "doSomethingCostly");
/// ...
/// }
/// </pre>
///
/// Additional parameters can be associated with an event:
/// <pre>
/// void doSomethingCostly2(int howMuch) {
/// TRACE_EVENT1("MY_SUBSYSTEM", "doSomethingCostly",
/// "howMuch", howMuch);
/// ...
/// }
/// </pre>
///
/// The trace system will automatically add to this information the current
/// process id, thread id, and a timestamp in microseconds.
///
/// To trace an asynchronous procedure such as an IPC send/receive, use
/// ASYNC_BEGIN and ASYNC_END:
/// <pre>
/// [single threaded sender code]
/// static int send_count = 0;
/// ++send_count;
/// TRACE_EVENT_ASYNC_BEGIN0("ipc", "message", send_count);
/// Send(new MyMessage(send_count));
/// [receive code]
/// void OnMyMessage(send_count) {
/// TRACE_EVENT_ASYNC_END0("ipc", "message", send_count);
/// }
/// </pre>
/// The third parameter is a unique ID to match ASYNC_BEGIN/ASYNC_END pairs.
/// ASYNC_BEGIN and ASYNC_END can occur on any thread of any traced process.
/// Pointers can be used for the ID parameter, and they will be mangled
/// internally so that the same pointer on two different processes will not
/// match. For example:
/// <pre>
/// class MyTracedClass {
/// public:
/// MyTracedClass() {
/// TRACE_EVENT_ASYNC_BEGIN0("category", "MyTracedClass", this);
/// }
/// ~MyTracedClass() {
/// TRACE_EVENT_ASYNC_END0("category", "MyTracedClass", this);
/// }
/// }
/// </pre>
///
/// The trace event also supports counters, which is a way to track a quantity
/// as it varies over time. Counters are created with the following macro:
/// <pre>
/// TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter", g_myCounterValue);
/// </pre>
///
/// Counters are process-specific. The macro itself can be issued from any
/// thread, however.
///
/// Sometimes, you want to track two counters at once. You can do this with two
/// counter macros:
/// <pre>
/// TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter0", g_myCounterValue[0]);
/// TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter1", g_myCounterValue[1]);
/// </pre>
/// Or you can do it with a combined macro:
/// <pre>
/// TRACE_COUNTER2("MY_SUBSYSTEM", "myCounter",
/// "bytesPinned", g_myCounterValue[0],
/// "bytesAllocated", g_myCounterValue[1]);
/// </pre>
/// This indicates to the tracing UI that these counters should be displayed
/// in a single graph, as a summed area chart.
///
/// Since counters are in a global namespace, you may want to disembiguate with
/// a unique ID, by using the TRACE_COUNTER_ID* variations.
///
/// By default, trace collection is compiled in, but turned off at runtime.
/// Collecting trace data is the responsibility of the embedding application. In
/// CEF's case, calling BeginTracing will turn on tracing on all active
/// processes.
///
///
/// Memory scoping note:
/// Tracing copies the pointers, not the string content, of the strings passed
/// in for category, name, and arg_names. Thus, the following code will cause
/// problems:
/// <pre>
/// char* str = strdup("impprtantName");
/// TRACE_EVENT_INSTANT0("SUBSYSTEM", str); // BAD!
/// free(str); // Trace system now has dangling pointer
/// </pre>
///
/// To avoid this issue with the |name| and |arg_name| parameters, use the
/// TRACE_EVENT_COPY_XXX overloads of the macros at additional runtime
/// overhead.
///
/// Notes: The category must always be in a long-lived char* (i.e. static
/// const). The |arg_values|, when used, are always deep copied with
/// the _COPY macros.
///
///
/// Thread Safety:
/// All macros are thread safe and can be used from any process.
///
#ifndef CEF_INCLUDE_BASE_CEF_TRACE_EVENT_H_
@ -141,7 +163,7 @@
#pragma once
#if defined(USING_CHROMIUM_INCLUDES)
// When building CEF include the Chromium header directly.
/// When building CEF include the Chromium header directly.
#include "base/trace_event/trace_event.h"
#else // !USING_CHROMIUM_INCLUDES
// The following is substantially similar to the Chromium implementation.
@ -150,11 +172,13 @@
#include "include/internal/cef_trace_event_internal.h"
// Records a pair of begin and end events called "name" for the current
// scope, with 0, 1 or 2 associated arguments. If the category is not
// enabled, then this does nothing.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
///
/// Records a pair of begin and end events called "name" for the current
/// scope, with 0, 1 or 2 associated arguments. If the category is not
/// enabled, then this does nothing.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
///
#define TRACE_EVENT0(category, name) \
cef_trace_event_begin(category, name, NULL, 0, NULL, 0, false); \
CEF_INTERNAL_TRACE_END_ON_SCOPE_CLOSE(category, name)
@ -179,11 +203,13 @@
cef_trace_event::CefTraceEndOnScopeClose CEF_INTERNAL_TRACE_EVENT_UID( \
profileScope)(category, name)
// Records a single event called "name" immediately, with 0, 1 or 2
// associated arguments. If the category is not enabled, then this
// does nothing.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
///
/// Records a single event called "name" immediately, with 0, 1 or 2
/// associated arguments. If the category is not enabled, then this
/// does nothing.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
///
#define TRACE_EVENT_INSTANT0(category, name) \
cef_trace_event_instant(category, name, NULL, 0, NULL, 0, false)
#define TRACE_EVENT_INSTANT1(category, name, arg1_name, arg1_val) \
@ -201,11 +227,13 @@
cef_trace_event_instant(category, name, arg1_name, arg1_val, arg2_name, \
arg2_val, true)
// Records a single BEGIN event called "name" immediately, with 0, 1 or 2
// associated arguments. If the category is not enabled, then this
// does nothing.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
///
/// Records a single BEGIN event called "name" immediately, with 0, 1 or 2
/// associated arguments. If the category is not enabled, then this
/// does nothing.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
///
#define TRACE_EVENT_BEGIN0(category, name) \
cef_trace_event_begin(category, name, NULL, 0, NULL, 0, false)
#define TRACE_EVENT_BEGIN1(category, name, arg1_name, arg1_val) \
@ -223,10 +251,12 @@
cef_trace_event_begin(category, name, arg1_name, arg1_val, arg2_name, \
arg2_val, true)
// Records a single END event for "name" immediately. If the category
// is not enabled, then this does nothing.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
///
/// Records a single END event for "name" immediately. If the category
/// is not enabled, then this does nothing.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
///
#define TRACE_EVENT_END0(category, name) \
cef_trace_event_end(category, name, NULL, 0, NULL, 0, false)
#define TRACE_EVENT_END1(category, name, arg1_name, arg1_val) \
@ -244,20 +274,24 @@
cef_trace_event_end(category, name, arg1_name, arg1_val, arg2_name, \
arg2_val, true)
// Records the value of a counter called "name" immediately. Value
// must be representable as a 32 bit integer.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
///
/// Records the value of a counter called "name" immediately. Value
/// must be representable as a 32 bit integer.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
///
#define TRACE_COUNTER1(category, name, value) \
cef_trace_counter(category, name, NULL, value, NULL, 0, false)
#define TRACE_COPY_COUNTER1(category, name, value) \
cef_trace_counter(category, name, NULL, value, NULL, 0, true)
// Records the values of a multi-parted counter called "name" immediately.
// The UI will treat value1 and value2 as parts of a whole, displaying their
// values as a stacked-bar chart.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
///
/// Records the values of a multi-parted counter called "name" immediately.
/// The UI will treat value1 and value2 as parts of a whole, displaying their
/// values as a stacked-bar chart.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
///
#define TRACE_COUNTER2(category, name, value1_name, value1_val, value2_name, \
value2_val) \
cef_trace_counter(category, name, value1_name, value1_val, value2_name, \
@ -267,28 +301,32 @@
cef_trace_counter(category, name, value1_name, value1_val, value2_name, \
value2_val, true)
// Records the value of a counter called "name" immediately. Value
// must be representable as a 32 bit integer.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
// - |id| is used to disambiguate counters with the same name. It must either
// be a pointer or an integer value up to 64 bits. If it's a pointer, the
// bits will be xored with a hash of the process ID so that the same pointer
// on two different processes will not collide.
///
/// Records the value of a counter called "name" immediately. Value
/// must be representable as a 32 bit integer.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
/// - |id| is used to disambiguate counters with the same name. It must either
/// be a pointer or an integer value up to 64 bits. If it's a pointer, the
/// bits will be xored with a hash of the process ID so that the same pointer
/// on two different processes will not collide.
///
#define TRACE_COUNTER_ID1(category, name, id, value) \
cef_trace_counter_id(category, name, id, NULL, value, NULL, 0, false)
#define TRACE_COPY_COUNTER_ID1(category, name, id, value) \
cef_trace_counter_id(category, name, id, NULL, value, NULL, 0, true)
// Records the values of a multi-parted counter called "name" immediately.
// The UI will treat value1 and value2 as parts of a whole, displaying their
// values as a stacked-bar chart.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
// - |id| is used to disambiguate counters with the same name. It must either
// be a pointer or an integer value up to 64 bits. If it's a pointer, the
// bits will be xored with a hash of the process ID so that the same pointer
// on two different processes will not collide.
///
/// Records the values of a multi-parted counter called "name" immediately.
/// The UI will treat value1 and value2 as parts of a whole, displaying their
/// values as a stacked-bar chart.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
/// - |id| is used to disambiguate counters with the same name. It must either
/// be a pointer or an integer value up to 64 bits. If it's a pointer, the
/// bits will be xored with a hash of the process ID so that the same pointer
/// on two different processes will not collide.
///
#define TRACE_COUNTER_ID2(category, name, id, value1_name, value1_val, \
value2_name, value2_val) \
cef_trace_counter_id(category, name, id, value1_name, value1_val, \
@ -298,22 +336,24 @@
cef_trace_counter_id(category, name, id, value1_name, value1_val, \
value2_name, value2_val, true)
// Records a single ASYNC_BEGIN event called "name" immediately, with 0, 1 or 2
// associated arguments. If the category is not enabled, then this
// does nothing.
// - category and name strings must have application lifetime (statics or
// literals). They may not include " chars.
// - |id| is used to match the ASYNC_BEGIN event with the ASYNC_END event.
// ASYNC events are considered to match if their category, name and id values
// all match. |id| must either be a pointer or an integer value up to 64
// bits. If it's a pointer, the bits will be xored with a hash of the process
// ID sothat the same pointer on two different processes will not collide.
// An asynchronous operation can consist of multiple phases. The first phase is
// defined by the ASYNC_BEGIN calls. Additional phases can be defined using the
// ASYNC_STEP_BEGIN macros. When the operation completes, call ASYNC_END.
// An async operation can span threads and processes, but all events in that
// operation must use the same |name| and |id|. Each event can have its own
// args.
///
/// Records a single ASYNC_BEGIN event called "name" immediately, with 0, 1 or 2
/// associated arguments. If the category is not enabled, then this
/// does nothing.
/// - category and name strings must have application lifetime (statics or
/// literals). They may not include " chars.
/// - |id| is used to match the ASYNC_BEGIN event with the ASYNC_END event.
/// ASYNC events are considered to match if their category, name and id values
/// all match. |id| must either be a pointer or an integer value up to 64
/// bits. If it's a pointer, the bits will be xored with a hash of the process
/// ID sothat the same pointer on two different processes will not collide.
/// An asynchronous operation can consist of multiple phases. The first phase is
/// defined by the ASYNC_BEGIN calls. Additional phases can be defined using the
/// ASYNC_STEP_BEGIN macros. When the operation completes, call ASYNC_END.
/// An async operation can span threads and processes, but all events in that
/// operation must use the same |name| and |id|. Each event can have its own
/// args.
///
#define TRACE_EVENT_ASYNC_BEGIN0(category, name, id) \
cef_trace_event_async_begin(category, name, id, NULL, 0, NULL, 0, false)
#define TRACE_EVENT_ASYNC_BEGIN1(category, name, id, arg1_name, arg1_val) \
@ -333,12 +373,14 @@
cef_trace_event_async_begin(category, name, id, arg1_name, arg1_val, \
arg2_name, arg2_val, true)
// Records a single ASYNC_STEP_INTO event for |step| immediately. If the
// category is not enabled, then this does nothing. The |name| and |id| must
// match the ASYNC_BEGIN event above. The |step| param identifies this step
// within the async event. This should be called at the beginning of the next
// phase of an asynchronous operation. The ASYNC_BEGIN event must not have any
// ASYNC_STEP_PAST events.
///
/// Records a single ASYNC_STEP_INTO event for |step| immediately. If the
/// category is not enabled, then this does nothing. The |name| and |id| must
/// match the ASYNC_BEGIN event above. The |step| param identifies this step
/// within the async event. This should be called at the beginning of the next
/// phase of an asynchronous operation. The ASYNC_BEGIN event must not have any
/// ASYNC_STEP_PAST events.
///
#define TRACE_EVENT_ASYNC_STEP_INTO0(category, name, id, step) \
cef_trace_event_async_step_into(category, name, id, step, NULL, 0, false)
#define TRACE_EVENT_ASYNC_STEP_INTO1(category, name, id, step, arg1_name, \
@ -352,12 +394,14 @@
cef_trace_event_async_step_into(category, name, id, step, arg1_name, \
arg1_val, true)
// Records a single ASYNC_STEP_PAST event for |step| immediately. If the
// category is not enabled, then this does nothing. The |name| and |id| must
// match the ASYNC_BEGIN event above. The |step| param identifies this step
// within the async event. This should be called at the beginning of the next
// phase of an asynchronous operation. The ASYNC_BEGIN event must not have any
// ASYNC_STEP_INTO events.
///
/// Records a single ASYNC_STEP_PAST event for |step| immediately. If the
/// category is not enabled, then this does nothing. The |name| and |id| must
/// match the ASYNC_BEGIN event above. The |step| param identifies this step
/// within the async event. This should be called at the beginning of the next
/// phase of an asynchronous operation. The ASYNC_BEGIN event must not have any
/// ASYNC_STEP_INTO events.
///
#define TRACE_EVENT_ASYNC_STEP_PAST0(category, name, id, step) \
cef_trace_event_async_step_past(category, name, id, step, NULL, 0, false)
#define TRACE_EVENT_ASYNC_STEP_PAST1(category, name, id, step, arg1_name, \
@ -371,8 +415,10 @@
cef_trace_event_async_step_past(category, name, id, step, arg1_name, \
arg1_val, true)
// Records a single ASYNC_END event for "name" immediately. If the category
// is not enabled, then this does nothing.
///
/// Records a single ASYNC_END event for "name" immediately. If the category
/// is not enabled, then this does nothing.
///
#define TRACE_EVENT_ASYNC_END0(category, name, id) \
cef_trace_event_async_end(category, name, id, NULL, 0, NULL, 0, false)
#define TRACE_EVENT_ASYNC_END1(category, name, id, arg1_name, arg1_val) \
@ -394,7 +440,9 @@
namespace cef_trace_event {
// Used by TRACE_EVENTx macro. Do not use directly.
///
/// Used by TRACE_EVENTx macro. Do not use directly.
///
class CefTraceEndOnScopeClose {
public:
CefTraceEndOnScopeClose(const char* category, const char* name)
@ -408,7 +456,7 @@ class CefTraceEndOnScopeClose {
const char* name_;
};
} // cef_trace_event
} // namespace cef_trace_event
#endif // !USING_CHROMIUM_INCLUDES

47
include/base/cef_tuple.h
View File

@ -28,25 +28,30 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// Use std::tuple as tuple type. This file contains helper functions for
// working with std::tuples.
// The functions DispatchToMethod and DispatchToFunction take a function pointer
// or instance and method pointer, and unpack a tuple into arguments to the
// call.
//
// Example usage:
// // These two methods of creating a Tuple are identical.
// std::tuple<int, const char*> tuple_a(1, "wee");
// std::tuple<int, const char*> tuple_b = std::make_tuple(1, "wee");
//
// void SomeFunc(int a, const char* b) { }
// DispatchToFunction(&SomeFunc, tuple_a); // SomeFunc(1, "wee")
// DispatchToFunction(
// &SomeFunc, std::make_tuple(10, "foo")); // SomeFunc(10, "foo")
//
// struct { void SomeMeth(int a, int b, int c) { } } foo;
// DispatchToMethod(&foo, &Foo::SomeMeth, std::make_tuple(1, 2, 3));
// // foo->SomeMeth(1, 2, 3);
///
/// \file
/// Use std::tuple as tuple type. This file contains helper functions for
/// working with std::tuples.
/// The functions DispatchToMethod and DispatchToFunction take a function
/// pointer or instance and method pointer, and unpack a tuple into arguments to
/// the call.
///
/// Example usage:
/// <pre>
/// // These two methods of creating a Tuple are identical.
/// std::tuple<int, const char*> tuple_a(1, "wee");
/// std::tuple<int, const char*> tuple_b = std::make_tuple(1, "wee");
///
/// void SomeFunc(int a, const char* b) { }
/// DispatchToFunction(&SomeFunc, tuple_a); // SomeFunc(1, "wee")
/// DispatchToFunction(
/// &SomeFunc, std::make_tuple(10, "foo")); // SomeFunc(10, "foo")
///
/// struct { void SomeMeth(int a, int b, int c) { } } foo;
/// DispatchToMethod(&foo, &Foo::SomeMeth, std::make_tuple(1, 2, 3));
/// // foo->SomeMeth(1, 2, 3);
/// </pre>
///
#ifndef CEF_INCLUDE_BASE_CEF_TUPLE_H_
#define CEF_INCLUDE_BASE_CEF_TUPLE_H_
@ -88,9 +93,7 @@ inline void DispatchToMethodImpl(const ObjT& obj,
}
template <typename ObjT, typename Method, typename Tuple>
inline void DispatchToMethod(const ObjT& obj,
Method method,
Tuple&& args) {
inline void DispatchToMethod(const ObjT& obj, Method method, Tuple&& args) {
constexpr size_t size = std::tuple_size<std::decay_t<Tuple>>::value;
DispatchToMethodImpl(obj, method, std::forward<Tuple>(args),
std::make_index_sequence<size>());

271
include/base/cef_weak_ptr.h
View File

@ -28,69 +28,73 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// Weak pointers are pointers to an object that do not affect its lifetime,
// and which may be invalidated (i.e. reset to nullptr) by the object, or its
// owner, at any time, most commonly when the object is about to be deleted.
// Weak pointers are useful when an object needs to be accessed safely by one
// or more objects other than its owner, and those callers can cope with the
// object vanishing and e.g. tasks posted to it being silently dropped.
// Reference-counting such an object would complicate the ownership graph and
// make it harder to reason about the object's lifetime.
// EXAMPLE:
//
// class Controller {
// public:
// void SpawnWorker() { Worker::StartNew(weak_factory_.GetWeakPtr()); }
// void WorkComplete(const Result& result) { ... }
// private:
// // Member variables should appear before the WeakPtrFactory, to ensure
// // that any WeakPtrs to Controller are invalidated before its members
// // variable's destructors are executed, rendering them invalid.
// WeakPtrFactory<Controller> weak_factory_{this};
// };
//
// class Worker {
// public:
// static void StartNew(WeakPtr<Controller> controller) {
// Worker* worker = new Worker(std::move(controller));
// // Kick off asynchronous processing...
// }
// private:
// Worker(WeakPtr<Controller> controller)
// : controller_(std::move(controller)) {}
// void DidCompleteAsynchronousProcessing(const Result& result) {
// if (controller_)
// controller_->WorkComplete(result);
// }
// WeakPtr<Controller> controller_;
// };
//
// With this implementation a caller may use SpawnWorker() to dispatch multiple
// Workers and subsequently delete the Controller, without waiting for all
// Workers to have completed.
// ------------------------- IMPORTANT: Thread-safety -------------------------
// Weak pointers may be passed safely between threads, but must always be
// dereferenced and invalidated on the same ThreaddTaskRunner otherwise
// checking the pointer would be racey.
//
// To ensure correct use, the first time a WeakPtr issued by a WeakPtrFactory
// is dereferenced, the factory and its WeakPtrs become bound to the calling
// thread or current ThreaddWorkerPool token, and cannot be dereferenced or
// invalidated on any other task runner. Bound WeakPtrs can still be handed
// off to other task runners, e.g. to use to post tasks back to object on the
// bound thread.
//
// If all WeakPtr objects are destroyed or invalidated then the factory is
// unbound from the ThreaddTaskRunner/Thread. The WeakPtrFactory may then be
// destroyed, or new WeakPtr objects may be used, from a different thread.
//
// Thus, at least one WeakPtr object must exist and have been dereferenced on
// the correct thread to enforce that other WeakPtr objects will enforce they
// are used on the desired thread.
///
/// \file
/// Weak pointers are pointers to an object that do not affect its lifetime.
/// They may be invalidated (i.e. reset to nullptr) by the object, or its
/// owner, at any time, most commonly when the object is about to be deleted.
///
/// Weak pointers are useful when an object needs to be accessed safely by one
/// or more objects other than its owner, and those callers can cope with the
/// object vanishing and e.g. tasks posted to it being silently dropped.
/// Reference-counting such an object would complicate the ownership graph and
/// make it harder to reason about the object's lifetime.
///
/// EXAMPLE:
///
/// <pre>
/// class Controller {
/// public:
/// void SpawnWorker() { Worker::StartNew(weak_factory_.GetWeakPtr()); }
/// void WorkComplete(const Result& result) { ... }
/// private:
/// // Member variables should appear before the WeakPtrFactory, to ensure
/// // that any WeakPtrs to Controller are invalidated before its members
/// // variable's destructors are executed, rendering them invalid.
/// WeakPtrFactory<Controller> weak_factory_{this};
/// };
///
/// class Worker {
/// public:
/// static void StartNew(WeakPtr<Controller> controller) {
/// Worker* worker = new Worker(std::move(controller));
/// // Kick off asynchronous processing...
/// }
/// private:
/// Worker(WeakPtr<Controller> controller)
/// : controller_(std::move(controller)) {}
/// void DidCompleteAsynchronousProcessing(const Result& result) {
/// if (controller_)
/// controller_->WorkComplete(result);
/// }
/// WeakPtr<Controller> controller_;
/// };
/// </pre>
///
/// With this implementation a caller may use SpawnWorker() to dispatch multiple
/// Workers and subsequently delete the Controller, without waiting for all
/// Workers to have completed.
///
/// <b>IMPORTANT: Thread-safety</b>
///
/// Weak pointers may be passed safely between threads, but must always be
/// dereferenced and invalidated on the same ThreaddTaskRunner otherwise
/// checking the pointer would be racey.
///
/// To ensure correct use, the first time a WeakPtr issued by a WeakPtrFactory
/// is dereferenced, the factory and its WeakPtrs become bound to the calling
/// thread or current ThreaddWorkerPool token, and cannot be dereferenced or
/// invalidated on any other task runner. Bound WeakPtrs can still be handed
/// off to other task runners, e.g. to use to post tasks back to object on the
/// bound thread.
///
/// If all WeakPtr objects are destroyed or invalidated then the factory is
/// unbound from the ThreadedTaskRunner/Thread. The WeakPtrFactory may then be
/// destroyed, or new WeakPtr objects may be used, from a different thread.
///
/// Thus, at least one WeakPtr object must exist and have been dereferenced on
/// the correct thread to enforce that other WeakPtr objects will enforce they
/// are used on the desired thread.
#ifndef CEF_INCLUDE_BASE_CEF_WEAK_PTR_H_
#define CEF_INCLUDE_BASE_CEF_WEAK_PTR_H_
@ -243,27 +247,32 @@ class SupportsWeakPtrBase {
template <typename T>
class WeakPtrFactory;
// The WeakPtr class holds a weak reference to |T*|.
//
// This class is designed to be used like a normal pointer. You should always
// null-test an object of this class before using it or invoking a method that
// may result in the underlying object being destroyed.
//
// EXAMPLE:
//
// class Foo { ... };
// WeakPtr<Foo> foo;
// if (foo)
// foo->method();
//
///
/// The WeakPtr class holds a weak reference to |T*|.
///
/// This class is designed to be used like a normal pointer. You should always
/// null-test an object of this class before using it or invoking a method that
/// may result in the underlying object being destroyed.
///
/// EXAMPLE:
///
/// <pre>
/// class Foo { ... };
/// WeakPtr<Foo> foo;
/// if (foo)
/// foo->method();
/// </pre>
///
template <typename T>
class WeakPtr : public internal::WeakPtrBase {
public:
WeakPtr() = default;
WeakPtr(std::nullptr_t) {}
// Allow conversion from U to T provided U "is a" T. Note that this
// is separate from the (implicit) copy and move constructors.
///
/// Allow conversion from U to T provided U "is a" T. Note that this
/// is separate from the (implicit) copy and move constructors.
///
template <typename U>
WeakPtr(const WeakPtr<U>& other) : WeakPtrBase(other) {
// Need to cast from U* to T* to do pointer adjustment in case of multiple
@ -292,21 +301,27 @@ class WeakPtr : public internal::WeakPtrBase {
return get();
}
// Allow conditionals to test validity, e.g. if (weak_ptr) {...};
///
/// Allow conditionals to test validity, e.g. `if (weak_ptr) {...}`;
///
explicit operator bool() const { return get() != nullptr; }
// Returns false if the WeakPtr is confirmed to be invalid. This call is safe
// to make from any thread, e.g. to optimize away unnecessary work, but
// operator bool() must always be called, on the correct thread, before
// actually using the pointer.
//
// Warning: as with any object, this call is only thread-safe if the WeakPtr
// instance isn't being re-assigned or reset() racily with this call.
///
/// Returns false if the WeakPtr is confirmed to be invalid. This call is safe
/// to make from any thread, e.g. to optimize away unnecessary work, but
/// operator bool() must always be called, on the correct thread, before
/// actually using the pointer.
///
/// Warning: as with any object, this call is only thread-safe if the WeakPtr
/// instance isn't being re-assigned or reset() racily with this call.
///
bool MaybeValid() const { return ref_.MaybeValid(); }
// Returns whether the object |this| points to has been invalidated. This can
// be used to distinguish a WeakPtr to a destroyed object from one that has
// been explicitly set to null.
///
/// Returns whether the object |this| points to has been invalidated. This can
/// be used to distinguish a WeakPtr to a destroyed object from one that has
/// been explicitly set to null.
///
bool WasInvalidated() const { return ptr_ && !ref_.IsValid(); }
private:
@ -320,7 +335,9 @@ class WeakPtr : public internal::WeakPtrBase {
: WeakPtrBase(ref, reinterpret_cast<uintptr_t>(ptr)) {}
};
// Allow callers to compare WeakPtrs against nullptr to test validity.
///
/// Allow callers to compare WeakPtrs against nullptr to test validity.
///
template <class T>
bool operator!=(const WeakPtr<T>& weak_ptr, std::nullptr_t) {
return !(weak_ptr == nullptr);
@ -348,11 +365,14 @@ class WeakPtrFactoryBase {
};
} // namespace internal
// A class may be composed of a WeakPtrFactory and thereby
// control how it exposes weak pointers to itself. This is helpful if you only
// need weak pointers within the implementation of a class. This class is also
// useful when working with primitive types. For example, you could have a
// WeakPtrFactory<bool> that is used to pass around a weak reference to a bool.
///
/// A class may be composed of a WeakPtrFactory and thereby control how it
/// exposes weak pointers to itself. This is helpful if you only need weak
/// pointers within the implementation of a class. This class is also useful
/// when working with primitive types. For example, you could have a
/// WeakPtrFactory<bool> that is used to pass around a weak reference to a
/// bool.
///
template <class T>
class WeakPtrFactory : public internal::WeakPtrFactoryBase {
public:
@ -371,24 +391,30 @@ class WeakPtrFactory : public internal::WeakPtrFactoryBase {
reinterpret_cast<T*>(ptr_));
}
// Call this method to invalidate all existing weak pointers.
///
/// Call this method to invalidate all existing weak pointers.
///
void InvalidateWeakPtrs() {
DCHECK(ptr_);
weak_reference_owner_.Invalidate();
}
// Call this method to determine if any weak pointers exist.
///
/// Call this method to determine if any weak pointers exist.
///
bool HasWeakPtrs() const {
DCHECK(ptr_);
return weak_reference_owner_.HasRefs();
}
};
// A class may extend from SupportsWeakPtr to let others take weak pointers to
// it. This avoids the class itself implementing boilerplate to dispense weak
// pointers. However, since SupportsWeakPtr's destructor won't invalidate
// weak pointers to the class until after the derived class' members have been
// destroyed, its use can lead to subtle use-after-destroy issues.
///
/// A class may extend from SupportsWeakPtr to let others take weak pointers to
/// it. This avoids the class itself implementing boilerplate to dispense weak
/// pointers. However, since SupportsWeakPtr's destructor won't invalidate
/// weak pointers to the class until after the derived class' members have been
/// destroyed, its use can lead to subtle use-after-destroy issues.
///
template <class T>
class SupportsWeakPtr : public internal::SupportsWeakPtrBase {
public:
@ -408,24 +434,29 @@ class SupportsWeakPtr : public internal::SupportsWeakPtrBase {
internal::WeakReferenceOwner weak_reference_owner_;
};
// Helper function that uses type deduction to safely return a WeakPtr<Derived>
// when Derived doesn't directly extend SupportsWeakPtr<Derived>, instead it
// extends a Base that extends SupportsWeakPtr<Base>.
//
// EXAMPLE:
// class Base : public base::SupportsWeakPtr<Producer> {};
// class Derived : public Base {};
//
// Derived derived;
// base::WeakPtr<Derived> ptr = base::AsWeakPtr(&derived);
//
// Note that the following doesn't work (invalid type conversion) since
// Derived::AsWeakPtr() is WeakPtr<Base> SupportsWeakPtr<Base>::AsWeakPtr(),
// and there's no way to safely cast WeakPtr<Base> to WeakPtr<Derived> at
// the caller.
//
// base::WeakPtr<Derived> ptr = derived.AsWeakPtr(); // Fails.
///
/// Helper function that uses type deduction to safely return a WeakPtr<Derived>
/// when Derived doesn't directly extend SupportsWeakPtr<Derived>, instead it
/// extends a Base that extends SupportsWeakPtr<Base>.
///
/// EXAMPLE:
/// <pre>
/// class Base : public base::SupportsWeakPtr<Producer> {};
/// class Derived : public Base {};
///
/// Derived derived;
/// base::WeakPtr<Derived> ptr = base::AsWeakPtr(&derived);
/// </pre>
///
/// Note that the following doesn't work (invalid type conversion) since
/// Derived::AsWeakPtr() is WeakPtr<Base> SupportsWeakPtr<Base>::AsWeakPtr(),
/// and there's no way to safely cast WeakPtr<Base> to WeakPtr<Derived> at
/// the caller.
///
/// <pre>
/// base::WeakPtr<Derived> ptr = derived.AsWeakPtr(); // Fails.
/// </pre>
///
template <typename Derived>
WeakPtr<Derived> AsWeakPtr(Derived* t) {
return internal::SupportsWeakPtrBase::StaticAsWeakPtr<Derived>(t);