Interfaces for posting base::Callbacks “tasks” to be run by the TaskRunner. TaskRunner makes no guarantees about execution (order, concurrency, or if it's even run at all). SequencedTaskRunner offers certain guarantees about the sequence of execution (roughly speaking FIFO, but see the header for nitty gritty details if interested) and SingleThreadTaskRunner offers the same guarantees as SequencedTaskRunner except all tasks run on the same thread. MessageLoopProxy is the canonical example of a SingleThreadTaskRunner. These interfaces are also useful for testing via dependency injection. NOTE: successfully posting to a TaskRunner does not necessarily mean the task will run.
NOTE: A very useful member function of TaskRunner is PostTaskAndReply(), which will post a task to a target TaskRunner and on completion post a “reply” task to the origin TaskRunner.
These are various APIs for posting a task. MessageLoop is a concrete object used by MessageLoopProxy (the most widely used task runner in Chromium code). You should almost always use MessageLoopProxy instead of MessageLoop, or if you're in chrome/ or content/, you can use BrowserThread. This is to avoid races on MessageLoop destruction, since MessageLoopProxy and BrowserThread will delete the task if the underlying MessageLoop is already destroyed. NOTE: successfully posting to a MessageLoop(Proxy) does not necessarily mean the task will run.
PS: There‘s some debate about when to use SequencedTaskRunner vs MessageLoopProxy vs BrowserThread. Using an interface class like SequencedTaskRunner makes the code more abstract/reusable/testable. On the other hand, due to the extra layer of indirection, it makes the code less obvious. Using a concrete BrowserThread ID makes it immediately obvious which thread it’s running on, although arguably you could name the SequencedTaskRunner variable appropriately to make it more clear. The current decision is to only convert code from BrowserThread to a TaskRunner subtype when necessary. MessageLoopProxy should probably always be passed around as a SingleThreadTaskRunner or a parent interface like SequencedTaskRunner.
These are the two primary worker pools in Chromium. SequencedWorkerPool is a more complicated worker pool that inherits from TaskRunner and provides ways to order tasks in a sequence (by sharing a SequenceToken) and also specifies shutdown behavior (block shutdown on task execution, do not run the task if the browser is shutting down and it hasn‘t started yet but if it has then block on it, or allow the task to run irrespective of browser shutdown and don’t block shutdown on it). SequencedWorkerPool also provides a facility to return a SequencedTaskRunner based on a SequenceToken. The Chromium browser process will shutdown base::SequencedWorkerPool after all main browser threads (other than the main thread) have stopped. base::WorkerPool is a global object that is not shutdown on browser process shutdown, so all the tasks running on it will not be joined. It's generally unadvisable to use base::WorkerPool since tasks may have dependencies on other objects that may be in the process of being destroyed during browser shutdown.
base::Callback is a set of internally refcounted templated callback classes with different arities and return values (including void). Note that these callbacks are copyable, but share (via refcounting) internal storage for the function pointer and the bound arguments. base::Bind() will bind arguments to a function pointer (under the hood, it copies the function pointer and all arguments into an internal refcounted storage object) and returns a base::Callback.
base::Bind() will automagically AddRef()/Release() the first argument if the function is a member function and will complain if the type is not refcounted (avoid this problem with base::WeakPtr or base::Unretained()). Also, for the function arguments, it will use a COMPILE_ASSERT to try to verify they are not raw pointers to a refcounted type (only possible with full type information, not forward declarations). Instead, use scoped_refptrs or call make_scoped_refptr() to prevent bugs. In addition, base::Bind() understands base::WeakPtr. If the function is a member function and the first argument is a base::WeakPtr to the object, base::Bind() will inject a wrapper function that only invokes the function pointer if the base::WeakPtr is non-NULL. base::Bind() also has the following helper wrappers for arguments.
Reference counting is occasionally useful but is more often a sign that someone isn't thinking carefully about ownership. Use it when ownership is truly shared (for example, multiple tabs sharing the same renderer process), not for when lifetime management is difficult to reason about.
They‘re globals, so you generally should avoid using them, as per the style guide. That said, when you use globals in Chromium code, it’s often good to use one of these, and in general, prefer base::LazyInstance over Singleton. The reason to use these classes is construction is lazy (thereby preventing startup slowdown due to static initializers) and destruction order is well-defined. They are all destroyed in opposite order as construction when the AtExitManager is destroyed. In the Chromium browser process, the AtExitManager is instantiated early on in the main thread (the UI thread), so all of these objects will be destroyed on the main thread, even if constructed on a different thread. The reason to prefer base::LazyInstance over base::Singleton is base::LazyInstance reduces heap fragmentation by reserving space in the data segment and using placement new to construct the object in that memory location. NOTE: Both Singleton and base::LazyInstance provide “leaky” traits to leak the global on shutdown. This is often advisable (except potentially in library code where the code may be dynamically loaded into another process's address space or when data needs to be flushed on process shutdown) in order to not to slow down shutdown. There are valgrind suppressions for these “leaky” traits.
Generally you shouldn't use these, since you should usually post tasks to an existing TaskRunner. PlatformThread is a platform-specific thread. base::Thread contains a MessageLoop running on a PlatformThread.
Mostly thread-unsafe weak pointer that returns NULL if the referent has been destroyed. It's safe to pass across threads (and to destroy on other threads), but it should only be used on the original thread it was created on. base::WeakPtrFactory is useful for automatically canceling base::Callbacks when the referent of the base::WeakPtr gets destroyed.
A cross-platform representation of a file path. You should generally use this instead of platform-specific representations.
ObserverList is a thread-unsafe object that is intended to be used as a member variable of a class. It provides a simple interface for iterating on a bunch of Observer objects and invoking a notification method.
ObserverListThreadSafe similar. It contains multiple ObserverLists, and observer notifications are invoked on the same PlatformThreadId that the observer was registered on, thereby allowing proxying notifications across threads and allowing the individual observers to receive notifications in a single threaded manner.
Pickle provides a basic facility for object serialization and deserialization in binary form.
Values allow for specifying recursive data classes (lists and dictionaries) containing simple values (bool/int/string/etc). These values can also be serialized to JSON and back.
This is the basic interface for logging in Chromium.
Generally you should not do file I/O on jank-sensitive threads (BrowserThread::UI and BrowserThread::IO), so you can proxy them to another thread (such as BrowserThread::FILE) via these utilities.
Generally use TimeTicks instead of Time to keep a stable tick counter (Time may change if the user changes the computer clock).
Containers for persistent state associated with a user Profile.