RE: [boost] Pool Review: Documentation

From: Jeff Garland (jeff_at_[hidden])
Date: 2000-12-04 23:23:03

> > [Jeff Garland]
> > You should add Bulka and Mayhew (Efficient C++, ISBN 0-201-37950-3) to
>
> I'll pick up this book, read it, and add it to the references.

Good!

> > [Jeff Garland]
> > 1) User examples are needed.  Please, some usage examples
>
> This is on the TODO list.

Ok, hopefully sooner rather than later....

> > 2) Ok, so what's the advantage?  As a user I want to seem some example
> 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.

Most developers won't be users unless you spell some of this out.

> Faster performance and (possibly) reduced memory usage are the advantages.

Hmmm...I guess I'm expecting higher memory usage typically with a fixed
pool?

> The disadvantages are more complicated code and loss of generality.  It is

I agree the code is more complicated, but fortunately for us you have
written most of it :)  I'm not sure what you mean by "generality".  In many
cases the user code isn't really different....

> *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...

That's the point isn't it?  It really is magic!

> 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.

I don't think you need to report results for every platform.  On the other
hand, if you don't report any results I'm not even sure you can claim the
library fulfills its purpose. I suggest you report "the results" for one
combination, provide the source for the tests and let the users run the
benchmarks on their own platform/compiler.  Hopefully some users will submit
new and interesting benchmarks.

> > 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".

My final push on this subject will be to suggest you have a look at the page
below:
http://www.boost.org/libs/smart_ptr/smarttests.htm
The summary provides a one paragraph description of some of the performance
factors to consider in smart pointer usage.  This doesn't eliminate the need
for me to go run my own tests, but it helps me focus my time.  By the way,
I'm expecting other boosters to help you out with this :)

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

Well, if the one I upload is correct, it's yours for free.  If you want to
link it to files I can send you some html that should do the trick...

Jeff