[boost] More threads review

From: David Abrahams (dave_at_[hidden])
Date: 2002-10-17 17:47:35

tss.html -

  Template thread_specific_ptr stores a pointer to an object obtained
  via new on a thread-by-thread basis and calls delete on the
  contained pointer when the thread terminates. Each thread initially
  stores the null pointer in each thread_specific_ptr instance.

This is really unclear. What does "on a thread-by-thread basis" mean?
[I know what it means now, but I didn't until I inspected the
implementation]. What is "the thread"? We're talking about multiple
threads here. Here's what I think users need to know about
thread_specific_ptr:

An instance of thread_specific_ptr<T>:

  - stores a T* associated with each thread. This T* is initially 0.

  - exposes a different value to each thread that accesses it (thus,
  it is possible to use mutating and non-mutating operations on the
  instance in any combination from multiple threads without invoking
  undefined behavior).

  - causes the expression `delete x' to be evaluated for each stored
    T* x when its associated thread terminates.

The note on the destructor is confusing. It says:

  "Does not destroy any data that may be stored in any thread's thread
   specific storage."

...OK...

   "For this reason you should not destroy a thread_specific_ptr
   object until you are certain there are no threads running that have
   made use of its thread specific storage."

But the second part doesn't follow from the first part at all. If it
doesn't destroy the thread-specific data, it should be safe to let the
thread continue running after the thread_specific_ptr is destroyed,
because the thread-specific data will hang around.

Also, "its" should be "their". 

Also, it would be better to stay away from terms like "thread-specific
data" and use the more-precise term "T* associated with the thread". I
can't suggest a complete rewording for this note because I don't
understand how to see the 2nd sentence as a consequence of the first
one.

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com
Building C/C++ Extensions for Python: Dec 9-11, Austin, TX
http://www.enthought.com/training/building_extensions.html