[v3] api docs

[Jonathan Wakely]

On 10/12/2007, Benjamin Kosnik <bkoz@redhat.com> wrote:
>
> > > 2) _GLIBCXX_ATOMIC_BUILTINS versus __default_lock_policy's
> > > __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2
> >
> > The latter exists specifically because the former is too broad and
> > doesn't guarantee that builtin CAS is available. IIRC configure
> > defines ATOMIC_BUILTINS if fetch-and-add is builtin, but fetch-and-add
> > is not a universal atomic primitive and can't be used to implement
> > arbitrary synchronisation operations, unlike CAS.
>
> 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.

> 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?
See tr1_impl/boost_shared_ptr.h (or tr1_impl/boost_sp_counted_base.h
once my reorganisation happens.)
_Sp_counted_base uses fetch_and_add and exchange_and_add through the
dispatchers in concurrence.h but it uses __sync_bool_compare_and_swap
directly.  This is for very good reason - fetch-and-add is not a
universal atomic primitive and cannot be used to implement a lock-free
shared_ptr.

> The only place it appears to be used is __default_lock_policy. And
> parallel mode. I'm working on 34106....
>
> I'd like to see a coherent lock policy for the whole library integrated
> into the ext/concurrency.h choices. It might mean that we need more
> choices in _Lock_policy. It might mean that the configure tests for
> _GLIBCXX_ATOMIC_BUILTINS gets adjusted.
>
> Right now, _GLIBCXX_ATOMIC_BUILTINS can be defined, but
> __default_lock_policy can be something else non-atomic. This seems
> incorrect to me.

It seems right to me. _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  :)

_GLIBCXX_ATOMIC_BUILTINS means that other bits of lock-free code (e.g.
std::string) can use a builtin fetch-and-add, which is still useful.
But that's not good enough for shared_ptr.

> > If configure checked for builtin CAS before defining ATOMIC_BUILTINS
> > it would mean builtin fetch-and-add and exchange-and-add would not be
> > used on some platforms where they are available.
>
> I'm not quite sure I follow.

Doesn't matter - bad idea anyway.  I meant the configure test could be
replaced by more pre-defined macros, but I don't think that's a good
idea.

> > The attached patch fixes some typos and markup.
>
> Thanks. Please put these in immediately.

Done.

> I was looking for a good firefox extension
> for doing W3C validation of local files, so I could see status on my
> local edits pre-checkin, but didn't have much luck. (And then I
> switched to konq so I could print 2-up anyway...)

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.

Jon