Finalization design #3

[kyren]

Makes as few decisions as possible and leaves everything up to the user.

Instead of having any direct finalization support, "simply" allows the user to stop collection at exactly the end of the marking phase and examine things.

Adds a finalize (indirect) method on Arena, and a new Finalization context which is currently Mutation but with two new powers:

• The ability to check whether a GcWeak was "dead" at the start of the current finalization call
• The ability to "resurrect" a GcWeak to preserve it this cycle (even without being upgraded and stored).

Entirely punts on ordering and queueing and leaves everything up to the user, BUT it is just powerful enough to implement finalizers and Java style ReferenceQueues and ephemeron tables and finalization ordering and many other things that parts 1 or 2 (or both) struggled with.

[kyren]

I have tested it in piccolo and am now using it to successfully implement Thread finalizers, so it seems to work pretty well!

[kyren]

Simplified API as per discussion on discord, we're just dropping the Finalization context entirely for now, it doesn't really add that much as is.

Other than that it's the same fundamental design which is still very simple.

At this point, the amount of actual meaningful code added is pretty small, it's mostly leaking a little more information and also a lot of new comments explaining things.

[kyren]

Undid some of the simplification for reasons outlined in the last commit message, which I'll copy here:

1) It makes documenting everything a little easier and prevents some misuses. When you call MarkedArena::finalize, you are examining the arena that WAS fully marked at the start of MarkedArena::finalize, and you know that in this state GcWeak::is_dead and GcWeak::resurrect have at least some meaning (that they were at least true at the beginning of the current MarkedArena::finalize call). Also, GcWeak::resurrect now always does something because we're always in the internal Mark phase. 2) The more important reason, it allows a user to protect against any resurrection funny business by a downstream user preventing access to MarkedArena. This is useful for libraries which want to provide a garbage collected arena but need to limit resurrection or at least control the precise order to maintain correctness.

[kyren]

This has been discussed to death on discord and it's gone through 4 or 5 revisions so it's been agreed that it's time to merge this, we still have plenty of time to change the API again before another crates.io release.