RE: [boost] Pool Review: Documentation

From: scleary_at_[hidden]
Date: 2000-12-04 10:30:06

> [Jeff Garland]
> You should add Bulka and Mayhew (Efficient C++, ISBN 0-201-37950-3) to
your
> concept references.  If you haven't looked at this reference, you should.

I'll pick up this book, read it, and add it to the references.

> [Jeff Garland]
> 1) User examples are needed.  Please, some usage examples somewhere in the
> docs

This is on the TODO list.

> [Jeff Garland]
> 2) Ok, so what's the advantage?  As a user I want to seem some example
(even
> trivial) of the advantages of taking the trouble to use a memory pool.  It
> seems to me it is critically important to have documentation of
performances
> gains.

I assumed that users of this library would be at least aware of how a pool
is supposed to work, and thus be aware of the advantages and disadvantages.
Faster performance and (possibly) reduced memory usage are the advantages.
The disadvantages are more complicated code and loss of generality.  It is
*not* only advantages; I don't want users plugging in pool to their code
everywhere thinking that it will magically make their program run 8x
faster...

> [Jeff Garland]
> Obviously this just scratches the surface.  Some other tests I would like
to
> see include MT versus no MT, slowdown due to pool reallocations, allocator
> tests, more complex objects, etc....

I thought of posting some timing results, similar to what you did.  But even
for the simple case, each possible compiler/library and OS combination would
have to be tested.  Simply put, I don't want to deal with this.  If someone
else would like to write timing tests and run them on different platforms,
they are free to do so.

> [Jeff Garland]
> 5) As boost users gain experience using these classes, there should also
be
> documentation on performance tuning.

Again, I don't know if I would be the one doing this.  I'm not exactly sure
what you mean by "performance tuning".

> [Jeff Garland]
> 1) The dependency diagram and documentation map in index.html renders
> strangely.  Thus I am left wondering what you mean.  Check out
> pool_dependencies.jpg in the uploaded files and see if it represents what
> you are trying to show.

I guess I'll bite the bullet and do something like this.  I'm just not
familiar with graphics editors.

> [Jeff Garland]
> 2) Copyright in the html should be at the bottom and in a readable font.

> [Jens Maurer]
>  - I would rather move the copyright/warranty notice to the bottom.

> [Gary Powell]
> Next: on IE5 the font for the copyright is unreadable. Its 
> way too small.

Will change.

> [Jeff Garland]
> 3) Garbage collection.  I would expunge the word garbage collection from
the
> documentation.  Pool is not a traditional garbage collector in the sense
of
> something which periodically runs to recollect memory. As you say it
> "provides automatic destruction".  I would add "upon destruction of the
> pool".

Agreed.  I'll change this, too.

> [Peter Dimov]
> * is there a list of the supported compilers? I haven't found one.

That's because I only have access to one compiler :).  I've tried to make it
portable, but some changes were already necessary to allow g++ to use it.
Presumably, this would be part of the test results page already in Boost.

> [Jens Maurer]
>  - The documentation needs some boost-ification.  At least the index.html
> page should have the standard boost logo and menu.

Will do.

> [Jens Maurer]
>  - The symbol "T" is often used for rather complex to-be-described
> types such as sized_pool.  I find this odd. . .

I'm willing to change this.

> [Jens Maurer]
>  - "synce" -> "since"

Heh. Thanks.

> [Jens Maurer]
>  - … is not recognized by Netscape 4.72.  Please check with the
> HTML standard to make sure it's legal.

It's legal: "horizontal ellipsis".  I can just change to three dots for
now... :)

> [Jens Maurer]
>  - "Simple Segregated Storage is the basic idea behind the Pool": this
> is the first time the term "Pool" is introduced in a defining context.
> However, it doesn't really define the term.  So, what's meant 
> by "Pool"?

I'll look this over.

> [Jens Maurer]
>  - Some of the HTML table-based diagrams are centred, others arent't,
> at least in my Netscpae 4.72.  I opt for consistency.

I'll check this, too.

> [Jens Maurer]
>  - In the diagrams: "Chunk X; points to NULL".

I'll change this.

> [Jens Maurer]
>  - Introduction: Please add a reference to the section number in the
> Standard where the Standard Allocator requirements are laid down

Will do.

> [Jens Maurer]
>  - Make the default template argument FirstArrayBound either
> explicitly implementation-defined or provide a specific value.

It should be implementation-defined.  I'll add this.

> [Jens Maurer]
>  - The return type for "t.free(p)" and "t.destroy(p)" is "void"
> and not "not used".

OK.

> [Jens Maurer]
>  - Please highlight in the "Introduction" section or somewhere else
> that the allocation functions return 0 on out-of-memory (instead of
> throwing std::bad_alloc) (yes, it's in the notes, but it may be
> overlooked easily).

Agreed.

> [Jens Maurer]
>  - Semantics: The symbol table says that "u" must be of type
> "void * const".  However, top-level constness is ignored for
> function parameter matching, so this seems useless.

Agreed.

> [Jens Maurer]
>  - Semantics: Is the exponential growth strategy only applied if I
> use the two-argument constructor? The description gives that
> impression.  If not, move that to a general section.

I'll move it out, then.  Perhaps this could be made clearer in general.
(The growth is exponential in terms of number of supported constructor
arguments).

> [Jens Maurer]
>  - Are memory blocks (allocated by new[]) ever freed again?  If
> not, please say so.

Only on pool destruction (right now).  I'll make that explicit.

        -Steve