Oilpan is a garbage collection system for Blink objects. This document explains the design of the GC. If you're just interested in how to use Oilpan, see BlinkGCAPIReference.
Oilpan is a single-threaded mark-and-sweep GC. It doesn't (yet) implement a generational or incremental GC.
Blink has multiple threads including the main thread, HTML parser threads, database threads and worker threads. Threads that touch Oilpan's heap need to be attached to Oilpan. These threads can have cross-thread pointers. Oilpan scans the object graph spanning these threads and collects unreachable objects.
Oilpan runs a GC in the following steps:
Step 1. A thread decides to trigger a GC. The thread can be any thread (it is likely to be the main thread because most allocations take place on the main thread). The thread is called a GCing thread.
Step 2. The GCing thread waits for all other threads to enter safe points. A safe point is a place where it‘s guaranteed that the thread does not mutate the object graph of objects in Oilpan’s heap. In common cases the thread stops at the safe point but doesn‘t necessarily need to stop. For example, the thread is allowed to execute a synchronous IO at the safe point as long as it doesn’t mutate the object graph. Safe points are inserted into many places so that the thread can enter the safe point as soon as possible when the GCing thread requests the thread to do so. For example, safe points are inserted into V8 interruptors, at the end of event loops, before acquiring a mutex, before starting a synchronous IO operation etc.
Step 3. Once all the threads enter the safe points, the GCing thread starts a marking phase. The GCing thread marks all objects reachable from the root set by calling trace() methods defined on each object. This means that the GCing thread marks objects owned by all the threads. This doesn't cause any threading race because all the other threads are at the safe points.
Step 4. Once the marking is complete, the GCing thread resumes executions of all the other threads. Each thread starts a sweeping phase. Each thread is responsible for destructing objects that the thread has allocated. That way objects are guaranteed to get destructed on the thread that has allocated the objects. The sweeping is done by each thread lazily. Instead of completing the sweeping phase in one go, the thread sweeps objects incrementally as much as it allocates. Lazy sweeping is helpful to distribute a long pause time of the sweeping phase into small chunks.
The step 2 and 3 is the pause time of the GC. The pause time is proportional to the number of objects marked in the marking phase, meaning that it is proportional to the number of live objects.
Notes:
If the GCing thread fails at stopping all the other threads in a certain period of time, it gives up triggering a GC. That way we avoid introducing an unacceptably long pause time. (This will rarely happen because each thread enters safe points very frequently.)
It is not really nice that the GCing thread has to stop all the other threads. For example, a worker thread has to get involved in a GC caused by a lot of allocations happening on the main thread. To resolve the issue, we have a plan to split the Oilpan‘s heap into per-thread heaps. Once it’s implemented, each thread can run GCs independently.
Oilpan has two kinds of GCs.
When all threads are stopped at the safe points at the end of event loops, a precise GC is triggered. At this point it is guaranteed that there are no on-stack pointers pointing to Oilpan's heap. Thus Oilpan runs a precise GC. The root set of a precise GC is persistent handles.
Otherwise, a conservative GC is triggered. In this case, the GC scans a native stack of the threads (which are not stopped at the safe points at the end of event loops) and push the pointers discovered via the native stacks into the root set. (That's why you can use raw pointers on the native stack.) The root set of a conservative GC is persistent handles and the native stacks of the threads.
A conservative GC is more expensive than a precise GC because the conservative GC needs to scan the native stacks. Thus Oilpan tries its best to trigger GCs at the end of an event loop. In particular, Oilpan tries its best to trigger GCs in idle tasks.
The marking phase (the step 3 in the above description) consists of the following steps. The marking phase is executed in a stop-the-world manner.
Step 3-1. The GCing thread marks all objects reachable from the root set by calling trace() methods defined on each object.
Step 3-2. The GCing thread clears out all trivial WeakMembers.
To prevent a use-after-free from happening, it is very important to make sure that Oilpan doesn‘t mis-trace any edge of the object graph. This means that all pointers except on-stack pointers must be wrapped with Oilpan’s handles (i.e., Persistent<>, Member<>, WeakMember<> etc). Raw pointers to on-heap objects have a risk of creating an edge Oilpan cannot understand and causing a use-after-free. You should not use raw pointers to on-heap objects (except raw pointers on native stacks) unless you're pretty sure that the target objects are guaranteed to be kept alive in other ways.
The sweeping phase (the step 4 in the above description) consists of the following steps. The sweeping phase is executed by each thread in parallel.
Step 4-1. The thread clears out all non-trivial WeakMembers. Non-trivial WeakMembers are the ones that have manual weak processing (registered by registerWeakMembers()) and the ones embedded in HeapHashMap etc. The reason we don‘t run non-trivial WeakMembers in the marking phase is that clearing out the non-trivial WeakMembers can invoke some destructors (e.g., if you have HeapHashMap<WeakMember, OwnPtr>, Y’s destructor is invoked when the weak processing removes the key). The destructors must run in the same thread that has allocated the objects.
Step 4-2. The thread invokes pre-finalizers. At this point, no destructors have been invoked. Thus the pre-finalizers are allowed to touch any other on-heap objects (which may get destructed in this sweeping phase).
Step 4-3. The thread invokes destructors of dead objects that are marked as eagerly-finalized. See the following notes for more details about the eagerly-finalized objects.
Step 4-4. The thread resumes mutator's execution. (A mutator means user code.)
Step 4-5. As the mutator allocates new objects, lazy sweeping invokes destructors of the remaining dead objects incrementally.
There is no guarantee of the order in which the destructors are invoked. That's why destructors must not touch any other on-heap objects (which might have already been destructed). If some destructor unavoidably needs to touch other on-heap objects, you need to use a pre-finalizer. The pre-finalizer is allowed to touch other on-heap objects.
The mutator is resumed before all the destructors has run. For example, imagine a case where X is a client of Y, and Y holds a list of clients. If you rely on X‘s destructor removing X from the list, there is a risk that Y iterates the list and calls some method of X which may touch other on-heap objects. This causes a use-after-free. You need to make sure that X is explicitly removed from the list before the mutator resumes its execution in a way that doesn’t rely on X's destructor.
Either way, the most important thing is that there is no guarantee of when destructors run. You shouldn‘t put any assumption about the order and the timing. (In general, it’s dangerous to do something complicated in a destructor.)
Notes (The followings are features you'll need only when you have unusual destruction requirements):
Weak processing runs only when the holder object of the WeakMember outlives the pointed object. If the holder object and the pointed object die at the same time, the weak processing doesn't run. It is wrong to write code assuming that the weak processing always runs.
Pre-finalizers are heavy because the thread needs to scan all pre-finalizers at each sweeping phase to determine which pre-finalizers to be invoked (the thread needs to invoke pre-finalizers of dead objects). You should avoid adding pre-finalizers to frequently created objects.
Eagerly-finalized objects are guaranteed to get destructed before the mutator resumes its execution. This means that a destructor of an eagerly-finalized object is allowed to touch other not-eagerly-finalized objects whereas it‘s not allowed to touch other eagerly-finalized objects. This notion is useful for some objects, but nasty. We’re planning to replace most eagerly-finalized objects with pre-finalizers.
There is a subtle scenario where a next GC is triggered before the thread finishes lazy sweeping. In that case, the not-yet-swept objects are marked as dead and the next GC starts. The objects marked as dead are swept in the sweeping phase of the next GC. This means that you cannot assume that some two objects get destructed in the same GC cycle.
Each thread has its dedicated heap so that the thread can allocate an object without acquiring a lock. For example, an object allocated on thread 1 goes to a different heap than an object allocated on thread 2.
In addition, each thread provides multiple arenas to group objects by their type and thus improves locality. For example, a Node object allocated on thread 1 goes to a different heap than a CSSValue object allocated on thread 1. (See BlinkGC.h to get the list of the typed arenas.)