JS engine modularization
The goal of this project is to incrementally tease apart JS engine source code into separate "modules" so that:
- it is easier to understand a module in isolation
- it is easier to get a high-level breakdown of SM code
- module dependencies are DAG-y as opposed to clique-y or spaghetti (as it is now)
The plan isn't to do anything radical to simulate "modules" in C++. Rather, we can just say a "module" X is a triple: X.cpp, X.h, X-inl.h. Here, X.h acts as the "module interface" to the rest of the code-base. X-inl.h contains inline files that are pulled out of X.h so that:
- X.h is more readable as a whole and
- we can reduce average translation unit size (which right now is hard because of the dependency clique).
The granularity of modules isn't fixed; the goal is to try to have a module encapsulate a coherent hunk of interdependent logic and implementation details. This may be a single type (e.g., js::Value) or a set of related types (the stack types in vm/Stack.h).
Additionally, we can use directories to group related modules. Again, this is primarily useful to assist newcomers in developing a hierarchical understanding of the code.
This is an incremental project. As developers work on a hunk of code, things tend to be rewritten/refactored into the new SpiderMonkey C++ style. Reviewers should require new code or major alterations to follow the new style unless it would be impractical.
Plan of Record
A meta bug tracks bugs for individual pieces. This document serves to collect consensus of the direction we'd like things to head.
Preliminary directory/module structure:
- js/src
- JSAPI implementation (jsapi.cpp, js::Invoke, js::Execute)
- Interpreter (ideally, if we had maximum code reuse, this would be just the one function calling lots of module (inline) functions)
- Grotty bits and bobs that don't make sense to modularize
- js/src/ds
- LifoAlloc, Vector, HashMap/Set, ...
- js/src/jit
- js/src/vm: central, execution-mode-independent data structures: types and operations
- Stack: execution stack (done)
- Value: JS value representation
- String: JS string value representation
- Perhaps these next two need short distinctive names:
- Low-level object representation: property tree, shapes, and raw object storage
- General high-level objects: high level generic set/get/call operations respecting JS semantics
- Class-specific high-level objects: statically typed interfaces for native objects of a given class
- Global: the global object
- Arguments: object accessed through 'arguments' keyword
- Function: (object) perhaps also contains closely-related JSFunctino/JSScript/Bindings?
- js/src/gc: garbage collector data structures and algorithms
- js/src/frontend: scanning, parsing, and emitting
- js/src/builtin: builtins specified by JS language spec (e.g., String, Array.prototype.sort)
- String
- Number
- Boolean
- Array
- Date
- Math
- ...
- js/src/devtools: code, config files and scripts that are generally useful to SM developers but not part of the official build