cds/init.h

   1 //$$CDS-header$$
   2
   3 #ifndef __CDS_INIT_H
   4 #define __CDS_INIT_H
   5
   6 #include <cds/details/defs.h>
   7 #include <cds/os/topology.h>
   8 #include <cds/threading/model.h>
   9 #include <cds/details/lib.h>
  10
  11 namespace cds {
  12
  13     //@cond
  14     namespace details {
  15         bool CDS_EXPORT_API init_first_call();
  16         bool CDS_EXPORT_API fini_last_call();
  17     }   // namespace details
  18     //@endcond
  19
  20     /// Initialize CDS library
  21     /**
  22         The function initializes \p CDS library framework.
  23         Before usage of \p CDS library features your application must initialize it
  24         by calling \p Initialize function:
  25         @code
  26         #include <cds/init.h>
  27         #include <cds/gc/hp.h>
  28
  29         int main()
  30         {
  31             // // Initialize CDS library
  32             cds::Initialize( 0 );
  33
  34             {
  35                 // // Initialize Hazard Pointer GC (if it is needed for you)
  36                 cds::gc::HP();
  37
  38                 // // Now you can use CDS library containers with Hazard Pointer GC
  39                 ...
  40
  41             }
  42             // // Teminate CDS library
  43             cds::Terminate();
  44
  45             return 0;
  46         }
  47         @endcode
  48
  49         You may call \p Initialize several times, only first call is significant others will be ignored.
  50         To terminate the \p CDS library correctly, each call to \p Initialize must be balanced by a corresponding call to \ref Terminate.
  51
  52         Note, that this function does not initialize garbage collectors. To use GC you need you should call
  53         GC-specific constructor function to initialize internal structures of GC. See cds::gc and its subnamespace for details.
  54     */
  55     static inline void Initialize(
  56         unsigned int nFeatureFlags = 0  ///< for future use, must be zero.
  57     )
  58     {
  59         CDS_UNUSED( nFeatureFlags );
  60
  61         if ( cds::details::init_first_call() )
  62         {
  63             cds::OS::topology::init();
  64             cds::threading::ThreadData::s_nProcCount = cds::OS::topology::processor_count();
  65             if ( cds::threading::ThreadData::s_nProcCount == 0 )
  66                 cds::threading::ThreadData::s_nProcCount = 1;
  67
  68             cds::threading::Manager::init();
  69         }
  70     }
  71
  72     /// Terminate CDS library
  73     /**
  74         This function terminates \p CDS library.
  75         After \p Terminate calling many features of the library are unavailable.
  76         This call should be the last call of \p CDS library in your application.
  77     */
  78     static inline void Terminate()
  79     {
  80         if ( cds::details::fini_last_call() ) {
  81             cds::threading::Manager::fini();
  82
  83             cds::OS::topology::fini();
  84         }
  85     }
  86
  87 }   // namespace cds
  88
  89 #endif // __CDS_INIT_H