some notes on dwarf_output::copier

[Mark Wielaard <mjw at redhat dot com>]

Just some notes that I made trying to figure out the state of the copier
and entry classes. More of a reference of all fields that hold state and
the control structures that exist to change them. Trying to figure out
what to change where to plug in the new setup/algorithm.

The dwarf_output::copier is responsible for transforming the input die
tree into unique dies in the collector, that then will make up the
dwarf_output dwarf hierarchy.

The copier is instantiated when a dwarf_output object is instantiated
and it creates the compile_units, which will call copier::make_unit ()
through the cu_maker for each cu. make_unit () will create a
copier::unit_copier for each cu using the
compile_units_type::const_iterator, and then calls final_unit () on it,
which just does a sanity check on the result, making sure there are no
undefined entries left, and returns the final die_info_pair.

copier::unit_copier is derived from copier::entry_copier and just makes
sure that the copier is setup, through a call to copier::enter
(input_die) to create a new copier::entry, and then a call to
entry_copier::populate () to setup the die children.

An entry_copier lives as long as the copier is transforming the
input_die. It holds the copier, the copier::entry input die, and a
copier::pending_entry output which gets created in the constructor from
the input die tag. The constructor set the input copier::entry
_m_building field to the entry_copier to indicate it is being
constructed. The destructor clears it again. It doesn't hold the actual
input_die as state, all methods take an input_die as argument.

entry_copier::populate (as called from the unit_copier constructor)
takes an input_die, sets the _m_pending field of the input entry to the
output pending_entry of the entry_copier. It will populate the
_m_attributes if the _m_out entry from the given input_die and call
add_child() for each child of the given input_die. After that it will
clear the _m_out field to indicate the we are done with the
pending_entry. And call entry::defined_self () on the _m_in entry.

When the _m_attributes set of the entry is populated the value maker
will call back into the entry_copier::add_reference() for each reference
value. add_reference() will setup the copier to enter the input_die to
which the attribute is pointing and provide a "backptr" to the
entry::refer() method that fill it in with either the finalized entry
itself (if it is finalized) or to the entry itself and pushes the
backptr to the _m_pending_refs of pending_entry.

entry_copier::add_child will setup the copier to start copying the given
child die and create a new copier::entry for it, add the child to the
_m_out pending_entry. If the child is already know, but not yet final
(because it comes from an DW_TAG_imported_unit in a logical walk) it
will update the _m_parent and create a new entry_copier and populate
that.

entry_copier::final_unit() as called from make_unit() will do sanity
checks to make sure the _m_in entry has really been finalized and return
the die_info_pair stored in the collector.

A copier::entry holds the following state: _m_offset, the Dwarff_Off of
the original die, _m_cost, the cost of the original die, _m_final a
pointer to a die_info_pair in the collector indicating this entry has
been finalized, _m_pending the pending entry state set by the
entry_copier, _m_parent entry pointing to direct parent, _m_building the
entry_copier (cleared on entry_copier destruction), _m_matching state
for the tracker, _m_self_idx used to find an child iterator to this
entry of its parent from a pending_entry, _m_final_ref "fake"
value_reference set and returned when self() is called to indicate the
entry is final but not yet "placed".

A copier::pending_entry holds the following sate: _m_tag the die tag,
_m_attributes the attributes, _m_children a vector of entry children,
_m_unfinished_children boolean to flag not all entry children are final,
_m_pending_regs stack of reference attribute values that aren't
resolved/final yet, _m_self a circular_reference to ourself,
_m_finalizing entry_finalizer set when actually finalizing the entry,
_m_matched and _m_mismatched caches for the tracker.

Next up is actually describing the control flow that changes the entry
and pending_entry state.