blink-gc-plugin

Blink GC Clang Plugin Development

This skill covers the end-to-end workflow for modifying the Blink GC (Oilpan) Clang plugin in //tools/clang/blink_gc_plugin/, testing it locally, fixing or suppressing violations across the codebase, rolling out the changes, and cleaning up the local environment afterwards.

1. Key Files and Architecture

• Plugin Entry Point & AST Consumer:
  • BlinkGCPlugin.cpp and BlinkGCPluginOptions.h: Plugin registration, command-line option definitions, and argument parsing.
  • BlinkGCPluginConsumer.h and BlinkGCPluginConsumer.cpp: Main ASTConsumer that orchestrates declaration collection, record/method validation, visitor checks, and AST matcher checks.
  • CollectVisitor.h and CollectVisitor.cpp: RecursiveASTVisitor that collects record declarations and tracing method definitions in the translation unit.
• Record & Points-To Edge Model:
  • RecordInfo.h and RecordInfo.cpp: Caches record properties (whether a type is garbage-collected, traceable, stack-allocated, or has fields/bases requiring tracing).
  • Edge.h, Edge.cpp, NeedsTracing.h, and TracingStatus.h: Models the type/field edge graph (Value, RawPtr, RefPtr, UniquePtr, Member, WeakMember, Persistent, CrossThreadPersistent, Collection, Iterator, ArrayEdge, etc.), EdgeVisitor / RecursiveEdgeVisitor, and tracing requirements.
• Visitor-Based Checks:
  • CheckFieldsVisitor.h and CheckFieldsVisitor.cpp: RecursiveEdgeVisitor that validates class fields (e.g. disallowing raw, scoped_refptr, or unique_ptr pointers to GC-managed/traceable types, disallowing Member in unmanaged classes, disallowing pointers from heap types to stack-allocated types, and disallowing GC-derived part objects).
  • CheckForbiddenFieldsVisitor.h and CheckForbiddenFieldsVisitor.cpp: RecursiveEdgeVisitor that checks that GC-managed classes and their embedded objects do not contain forbidden fields (such as TaskRunner or Mojo Remote/Receiver types).
  • CheckGCRootsVisitor.h and CheckGCRootsVisitor.cpp: RecursiveEdgeVisitor that checks that on-heap classes and their part objects do not contain GC roots (Persistent).
  • CheckTraceVisitor.h and CheckTraceVisitor.cpp: RecursiveASTVisitor that inspects Trace method bodies to verify all required bases and fields are traced.
  • CheckDispatchVisitor.h and CheckDispatchVisitor.cpp: RecursiveASTVisitor that verifies manual dispatch in TraceAfterDispatch and FinalizeGarbageCollectedObject methods.
  • CheckFinalizerVisitor.h and CheckFinalizerVisitor.cpp: RecursiveASTVisitor that checks destructors/finalizers do not access potentially finalized fields.
• AST Matcher-Based Checks:
  • BadPatternFinder.h and BadPatternFinder.cpp: Clang AST matchers for disallowed patterns involving Oilpan types (such as std::optional, absl::optional, std::variant, absl::variant, base::raw_ptr, base::raw_ref, std::unique_ptr, base::WeakPtr, off-heap collections, Member on stack, GCed variables/fields by value, and extra padding).
• Configuration, Diagnostics, Graph Dumping, and Tests:
  • Config.h and Config.cpp: Helpers for identifying Oilpan types, annotations (STACK_ALLOCATED, GC_PLUGIN_IGNORE), and smart pointer/collection names.
  • DiagnosticsReporter.h and DiagnosticsReporter.cpp: Diagnostic message templates and reporting methods.
  • JsonWriter.h and process-graph.py: Utilities for dumping (dump-graph) and processing the object graph.
  • //tools/clang/blink_gc_plugin/tests/: Lit-style golden tests (.cpp, .h, optional .flags, and expected .txt output files) run via test.py.