retainer profiling documentation

[Frederik Eaton]

I think the documentation for retainer profiling could be clearer...

> 5.4.2. Retainer Profiling
> 
> Retainer profiling is designed to help answer questions like "why is
> this data being retained?". We start by defining what we mean by a
> retainer:
> 
>     A retainer is either the system stack, or an unevaluated closure (thunk).
>
> In particular, constructors are not retainers.
> 
> An object A is retained by an object B if object A can be reached by
> recursively following pointers starting from object B but not meeting
> any other retainers on the way. Each object has one or more retainers,
> collectively called its retainer set.

I'm not sure I understand this but I'll try to rephrase it in a way
which I think is easier to parse.

> 5.4.2. Retainer Profiling
> 
> Retainer profiling is designed to help answer questions like "why is
> this data being retained?". We start by defining what we mean by a
> retainer object:
> 
>     A retainer object is either the system stack, or an unevaluated
>     closure (thunk).
>
> In particular, constructors are not retainer objects.
>
> Now we define what it means for one object to retain another:
>
>     An object B retains object A if it is a retainer object and
>     object A can be reached by recursively following pointers
>     starting from object B, but not meeting any other retainer
>     objects on the way. Each object is retained by one or more
>     retainer objects, collectively called its retainer set, or its
>     retainers.

Is this OK? I'm trying to distinguish the class of objects which are
allowed to be retainers - thunks and the stack - from ones which
actually retain other objects. E.g. one could have a thunk which
doesn't retain anything, I think it's confusing to define such a thing
as a "retainer", I thought "retainer object" would be clearer.

Frederik

-- 
http://ofb.net/~frederik/