Define "root" and rename methods of RootsWorkFactory

[wks]

The RootsWorkFactory trait is for VM bindings to report roots to mmtk-core.

pub trait RootsWorkFactory<SL: Slot>: Clone + Send + 'static {
    fn create_process_roots_work(&mut self, slots: Vec<SL>);
    fn create_process_pinning_roots_work(&mut self, nodes: Vec<ObjectReference>);
    fn create_process_tpinning_roots_work(&mut self, nodes: Vec<ObjectReference>);
}

The term "pinning roots" is a bit ambiguous.

The origin of the ambiguity comes from the term "root". According to the GC Handbook, a "root" is an object reference directly accessible by mutators. This means a "root" is held in a slot. But the GC Handbook also states that the term "root object" is also used to refer to an object directly referenced by a root. Because of this, when we use the word "root" alone, especially when it is represented as an ObjectReference, it is unclear whether it refers to

• the object reference (an edge), or
• the slot that holds the object reference (a slot), or
• the object pointed by that reference (a node).

So a "pinning root" (of type ObjectReference) may be interpreted as

1. a root reference that has the property of pinning the single object it points to, or
2. a root object that has the property of pinning its children.

Clarifying the terminology

I think we can make our terminology clear by defining the following terms and use them consistently within MMTk:

• "root slot": a slot directly accessible by mutators (i.e. global/local variables, etc.) that can hold an ObjectReference
• "root reference": an ObjectReference held in a root slot
• "root object": an object directly pointed by a root reference

We should add those in the Glossary which we recently added to our User Guide.

Renaming methods

create_*_*_*_work is quite a mouthful, and I'll delete the create_ and the _work from the names.

• create_process_roots_work -> root_slots
• create_process_pinning_roots_work -> pinned_root_objects
• create_process_tpinning_roots_work -> transitively_pinned_root_objects

A "pinned root object" makes it clear that (1) the object itself is pinned, and (2) it does not pin its children.

a "transitively pinned root object" makes it clear that (1) not only the object itself is pinned, but (2) its children are also pinned. I considered the term "transitively pinning root object", but it is ambiguous whether the object itself is pinned or not.

[qinsoon]

The function names are focusing on the semantics of the roots (normal vs pinning vs transitive pinning), rather than the representation of roots (slots vs node). I also feel it is okay.

In theory, you can have 6 variations: [normal, pinning, transitive pinning] x [slot, node]. The normal + node variation does not work for copying collectors.