[v3] api docs

[Benjamin Kosnik]

I'm dropping gcc-patches.

> > Configure defines _GLIBCXX_ATOMIC_BUILTINS if __sync_fetch_and_add
> > exists.
> 
> IIUC it's defined if is __sync_fetch_and_add is builtin - it might
> exist, but be implemented in a library.

Exactly right.

> > There is no use of CAS (via __sync_bool_compare_and_swap or
> > __sync_val_compare_and_swap) or other atomic builtins in
> > libstdc++.
> 
> Huh?

I see I was wrong on this.... 

> _S_atomic exists for shared_ptr, which requires
> a builtin CAS. It would be nice if __default_lock_policy was a general
> concurrence utility, but IMHO currently it's not. It's specific to
> shared_ptr's needs and any changes to it had better not break
> shared_ptr  :)

Got it.

However, we need _S_atomic or other to exist for more than
shared_ptr. As it stands now, I'm expecting the interface
to be ext/concurrence.h's _Lock_policy, not _GLIBCXX_ATOMIC_BUILTINS. 

ie, the documentation for extensions for threads/atomics vs. macros.

I'll do a more complete survey and see current usage before getting too
much further into this.

> I use the Web Developer Toolbar extension, which lets you validate a
> page with Ctrl-Shift-H or validate a local file:/// page with
> Ctrl-Shift-A - it also has loads of other features that I use now and
> then even though it's years since I did any web development.

Cool, thanks.

-benjamin

ps. gcc.gnu.org bounced my mail to gcc-patches yesterday. It too was
sent from gmail.