[v3] api docs

[Jonathan Wakely]

re-sending as this got rejected as spam by gcc-patches

On 10/12/2007, Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> 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
>