From 5f85a1ec75a564bb1707ca128854d5a9a95c75af Mon Sep 17 00:00:00 2001 From: khizmax Date: Sat, 4 Oct 2014 00:42:00 +0400 Subject: [PATCH] fix docs --- cds/container/treiber_stack.h | 34 +++++++++++++++++++++++----------- cds/cxx11_atomic.h | 6 +++--- cds/intrusive/treiber_stack.h | 17 +++++++++-------- cds/os/posix/thread.h | 2 ++ cds/os/win/thread.h | 2 ++ 5 files changed, 39 insertions(+), 22 deletions(-) diff --git a/cds/container/treiber_stack.h b/cds/container/treiber_stack.h index 32954b7e..5176e8ce 100644 --- a/cds/container/treiber_stack.h +++ b/cds/container/treiber_stack.h @@ -9,10 +9,13 @@ namespace cds { namespace container { + /// TreiberStack related definitions + /** @ingroup cds_nonintrusive_helper + */ namespace treiber_stack { /// Internal statistics template - using stat = cds::intrusive::treiber_stack::stat < Counter >; + using stat = cds::intrusive::treiber_stack::stat< Counter >; /// Dummy internal statistics typedef cds::intrusive::treiber_stack::empty_stat empty_stat; @@ -33,15 +36,15 @@ namespace cds { namespace container { */ typedef opt::v::relaxed_ordering memory_model; - /// Item counting feature; by default, disabled + /// Item counting feature; by default, disabled. Use \p cds::atomicity::item_counter to enable item counting typedef cds::atomicity::empty_item_counter item_counter; /// Internal statistics (by default, no internal statistics) /** - Possible option value are: \ref treiber_stack::stat, \ref treiber_stack::empty_stat (the default), + Possible types are: \ref treiber_stack::stat, \ref treiber_stack::empty_stat (the default), user-provided class that supports treiber_stack::stat interface. */ - typedef empty_stat stat; + typedef empty_stat stat; /** @name Elimination back-off traits The following traits is used only if elimination enabled @@ -80,10 +83,11 @@ namespace cds { namespace container { - opt::back_off - back-off strategy used. If the option is not specified, the \p cds::backoff::Default is used. - opt::memory_model - C++ memory ordering model. Can be \p opt::v::relaxed_ordering (relaxed memory model, the default) or \p opt::v::sequential_consistent (sequentially consisnent memory model). - - opt::item_counter - the type of item counting feature. Default is \p cds::atomicity::empty_item_counter + - opt::item_counter - the type of item counting feature. Default is \p cds::atomicity::empty_item_counter, i.e. + no item counting. Use \p cds::atomicity::item_counter to enable item counting. - opt::stat - the type to gather internal statistics. Possible option value are: \p treiber_stack::stat, \p treiber_stack::empty_stat (the default), - user-provided class that supports \p treiber_stack::stat interface. + user-provided class that supports \p %treiber_stack::stat interface. - opt::enable_elimination - enable elimination back-off for the stack. Default value is \p false. If elimination back-off is enabled, additional options can be specified: @@ -154,7 +158,7 @@ namespace cds { namespace container { typedef intrusive::TreiberStack< gc, node_type, intrusive_traits > type; }; } // namespace details - //@endecond + //@endcond /// Treiber's stack algorithm /** @ingroup cds_nonintrusive_stack @@ -162,15 +166,24 @@ namespace cds { namespace container { intrusive::TreiberStack. Template arguments: - - \p GC - garbage collector type: gc::HP, gc::PTB - - \p T - type stored in the stack. It should be default-constructible, copy-constructible, assignable type. + - \p GC - garbage collector type: \p gc::HP, gc::DHP + - \p T - type stored in the stack. - \p Traits - stack traits, default is \p treiber_stack::traits. You can use \p treiber_stack::make_traits metafunction to make your traits or just derive your traits from \p %treiber_stack::traits: \code struct myTraits: public cds::container::treiber_stack::traits { - typedef cds::container::treiber_stack::stat<> stat; + typedef cds::intrusive::treiber_stack::stat<> stat; + typedef cds::atomicity::item_counter item_counter; }; typedef cds::container::TreiberStack< cds::gc::HP, Foo, myTraits > myStack; + + // Equivalent make_traits example: + typedef cds::intrusive::TreiberStack< cds::gc::HP, Foo, + typename cds::intrusive::treiber_stack::make_traits< + cds::opt::item_counter< cds::atomicity::item_counter >, + cds::opt::stat< cds::intrusive::treiber_stack::stat<> > + >::type + > myStack; \endcode */ template < @@ -364,5 +377,4 @@ namespace cds { namespace container { }} // namespace cds::container - #endif // #ifndef __CDS_CONTAINER_TREIBER_STACK_H diff --git a/cds/cxx11_atomic.h b/cds/cxx11_atomic.h index 53f497db..bc33866e 100644 --- a/cds/cxx11_atomic.h +++ b/cds/cxx11_atomic.h @@ -10,7 +10,7 @@ namespace cds { /// C++11 Atomic library support /** \p libcds can use the following implementations of the atomics: - - STL . This is used by default + - STL \p <atomic>. This is used by default - \p boost.atomic for boost 1.54 and above. To use it you should define \p CDS_USE_BOOST_ATOMIC for your compiler invocation, for example, for gcc specify \p -DCDS_USE_BOOST_ATOMIC in command line @@ -22,13 +22,13 @@ namespace cds { ia64 (Itanium) 64bit, 64bit Sparc. To use \p libcds atomic you should define \p CDS_USE_LIBCDS_ATOMIC in the compiler command line (\p -DCDS_USE_LIBCDS_ATOMIC for gcc/clang). - @note For Clang compiler \p libcds do not use compiler-provided due some problems. + @note For Clang compiler \p libcds do not use compiler-provided \p <atomic> due some problems. Instead, \p libcds atomic is used by default, or you can try to use \p boost.atomic. The library defines \p atomics alias for atomic namespace: - namespace atomics = std for STL - namespace atomics = boost for \p boost.atomic - - namespace atomics = cds::cxx11_atomic for library-provided atomic implementation + - namespace atomics = cds::cxx11_atomic for library-provided atomic implementation */ namespace cxx11_atomic { }} // namespace cds::cxx11_atomic diff --git a/cds/intrusive/treiber_stack.h b/cds/intrusive/treiber_stack.h index 25787ac4..3b017512 100644 --- a/cds/intrusive/treiber_stack.h +++ b/cds/intrusive/treiber_stack.h @@ -154,8 +154,8 @@ namespace cds { namespace intrusive { /// The functor used for dispose removed items. Default is opt::v::empty_disposer. This option is used only in \ref TreiberStack::clear function typedef opt::v::empty_disposer disposer; - /// Item counting feature; by default, disabled - typedef cds::atomicity::empty_item_counter item_counter; + /// Item counting feature; by default, disabled. Use \p cds::atomicity::item_counter to enable item counting + typedef cds::atomicity::empty_item_counter item_counter; /// C++ memory ordering model /** @@ -208,7 +208,7 @@ namespace cds { namespace intrusive { This is a wrapper for cds::opt::make_options< type_traits, Options...> Supported \p Options are: - - opt::hook - hook used. Possible values are: treiber_stack::base_hook, treiber_stack::member_hook, treiber_stack::traits_hook. + - opt::hook - hook used. Possible values are: \p treiber_stack::base_hook, \p treiber_stack::member_hook, \p treiber_stack::traits_hook. If the option is not specified, \p %treiber_stack::base_hook<> is used. - opt::back_off - back-off strategy used. If the option is not specified, the \p cds::backoff::Default is used. - opt::disposer - the functor used for dispose removed items. Default is \p opt::v::empty_disposer. This option is used only @@ -216,7 +216,8 @@ namespace cds { namespace intrusive { - opt::link_checker - the type of node's link fields checking. Default is \ref opt::debug_check_link. - opt::memory_model - C++ memory ordering model. Can be \p opt::v::relaxed_ordering (relaxed memory model, the default) or \p opt::v::sequential_consistent (sequentially consisnent memory model). - - opt::item_counter - the type of item counting feature. Default is \p cds::atomicity::empty_item_counter + - opt::item_counter - the type of item counting feature. Default is \p cds::atomicity::empty_item_counter, i.e. + no item counting. Use \p cds::atomicity::item_counter to enable item counting. - opt::stat - the type to gather internal statistics. Possible option value are: \p treiber_stack::stat, \p treiber_stack::empty_stat (the default), user-provided class that supports \p treiber_stack::stat interface. @@ -423,9 +424,9 @@ namespace cds { namespace intrusive { This approach demonstrates sufficient performance under high load. Template arguments: - - \p GC - garbage collector type: gc::HP, gc::PTB. - Garbage collecting schema must be consistent with the \p treiber_stack::node GC. - - \p T - type to be inserted into the stack + - \p GC - garbage collector type: \p gc::HP, gc::DHP. + Garbage collecting schema must be the same as \p treiber_stack::node GC. + - \p T - a type the stack contains - \p Traits - stack traits, default is \p treiber_stack::traits. You can use \p treiber_stack::make_traits metafunction to make your traits or just derive your traits from \p %treiber_stack::traits: \code @@ -533,7 +534,7 @@ namespace cds { namespace intrusive { \endcode Example of how to use \p treiber_stack::member_hook. - Your class that will be pushed on \p %TreiberStack should have a member of type \p treiber_stack::node + Your class should have a member of type \p treiber_stack::node \code #include // offsetof macro #include diff --git a/cds/os/posix/thread.h b/cds/os/posix/thread.h index d8220dcf..5b8ddf92 100644 --- a/cds/os/posix/thread.h +++ b/cds/os/posix/thread.h @@ -29,11 +29,13 @@ namespace cds { namespace OS { } } // namespace posix + //@cond using posix::ThreadId; constexpr const ThreadId c_NullThreadId = 0; using posix::getCurrentThreadId; using posix::isThreadAlive; + //@endcond }} // namespace cds::OS diff --git a/cds/os/win/thread.h b/cds/os/win/thread.h index 0098bd8a..2185d7aa 100644 --- a/cds/os/win/thread.h +++ b/cds/os/win/thread.h @@ -29,11 +29,13 @@ namespace cds { namespace OS { } } // namespace Win32 + //@cond using Win32::ThreadId; CDS_CONSTEXPR const ThreadId c_NullThreadId = 0; using Win32::getCurrentThreadId; using Win32::isThreadAlive; + //@endcond }} // namespace cds::OS -- 2.34.1