retainer profiling documentation

[Simon Peyton-Jones]

Thanks for a constructive suggestion.  We've incorporated your
rewording.

I'll take this opportunity to encourage GHC users to offer suggested
rewording or clarifications to GHC's documentation.   We're far more
likely to do something if you suggest an improvement in concrete terms,
rather than simply say "this should be better documented" (which is
almost invariably true!).  And you're also in a much better position to
write clear documentation from the point of view of a user, than we are
as implementers.

Simon

| -----Original Message-----
| From: glasgow-haskell-bugs-bounces at haskell.org
[mailto:glasgow-haskell-bugs-
| bounces at haskell.org] On Behalf Of Frederik Eaton
| Sent: 09 March 2005 20:43
| To: glasgow-haskell-bugs at haskell.org
| Subject: retainer profiling documentation
| 
| 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/
| _______________________________________________
| Glasgow-haskell-bugs mailing list
| Glasgow-haskell-bugs at haskell.org
| http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs