1151554 - Add a comment to the top of Shape.h that explains the rationale for the complexity at a high level

Status: RESOLVED WORKSFORME

(Core :: JavaScript: GC, defect)

Description

[Terrence Cole [:terrence]]

After 2 days of reading Shape and jspropertytree code, I was still not seeing the big picture well enough to not break things when poking the internals. An hour of conversation with Jason on IRC fixed this by providing a high-level overview explaining the purpose of the various systems and how they interact.

Subjects covered include:
  * How lookups of obj[id] work against both inDictionary and !inDictionary shapes.
  * How property insertion works against !inDictionary shapes and why we need a propertytree.
  * Why the propertytree hashes on the full Shape info, but the ShapeTable only needs jsid.
  * How |parent| is the lineage for both InDictionary and !InDictionary, whereas, listp and kids are conceptually both the back-link; however listp is for deletion and kids is for insertion.

Topics not covered that would probably be helpful:
  * How IC's avoid all of this to go even faster.

In my opinion, being able to see how each operation -- lookup, insertion, and deletion -- works on the given layout makes it very clear what operations have a small O, why, and why the various structures are necessary to achieve that behavior. We should have a comment explaining all of this at the top of Shape.h. Sadly, I don't quite understand this all well enough yet to write that comment myself, although Jason has volunteered to take a stab at it.

Comment 1

[Jason Orendorff [:jorendorff]]

Taking in order to move this from one list to another in my dashboard. Don't get your hopes up.

Comment 2

[BugBot [:suhaib / :marco/ :calixte]]

The bug assignee didn't login in Bugzilla in the last 7 months, so the assignee is being reset.

Comment 3

[Jan de Mooij [:jandem]]

A lot of this changed and there are big comments in vm/Shape.h and vm/PropMap.h now.