[MLton-user] Documentation on finalizable values

[Vesa Karvonen]

I'm just about to use MLton's finalizable values for the first time and I
find the documentation on the page

  http://mlton.org/MLtonFinalizable

a bit confusing.  On the page it is said:

  "A finalizable value is a value to which finalizers can be attached. A
  finalizer is a function that runs after a garbage collection determines
  that the value to which it is attached is unreachable. Reachability is
  the same as with weak pointers."

In particular the last sentence quoted above (comparing to weak pointers)
is giving me trouble, because on the page

  http://mlton.org/MLtonWeak

it is said:

  "A weak pointer is a pointer to an object that is nulled if the object
  becomes unreachable due to garbage collection. The weak pointer does not
  itself cause the object it points to be retained by the garbage
  collector -- only other strong pointers can do that."

If I put those two quoted snippets together, it seems that even if a value
of type

  value_type MLton.Finalizable.t

is reachable then it isn't sufficient to retain the contained value of type
value_type.  However, looking at the example on the finalizable page, the
code is returning values of type

  Word32.word MLton.Finalizable.t

and it seems as though the contained values (of type Word32.word) are kept
alive as long as the finalizable value is alive.  This is even more confusing
as the documentation on weak pointers says:

  "For objects that are not allocated in the heap, like integers, a weak
  pointer will always be nulled."

So, if reachability of finalizable values would be the same as with weak
pointers, then a value of type

  Word32.word MLton.Finalizable.t

should be finalized immediately upon creation.  Or at least that is how I
would interpret it.

Assuming that I'm not missing something, then perhaps it would be best to
strike the sentence comparing the reachability of finalizable values with
that of weak pointers.  Also, perhaps a separate page explaining briefly
the concept of reachability could be useful.

-Vesa Karvonen