git.sesse.net Git - casparcg/blob - tbb/include/tbb/task_scheduler_init.h

   1 /*
   2     Copyright 2005-2011 Intel Corporation.  All Rights Reserved.
   3
   4     This file is part of Threading Building Blocks.
   5
   6     Threading Building Blocks is free software; you can redistribute it
   7     and/or modify it under the terms of the GNU General Public License
   8     version 2 as published by the Free Software Foundation.
   9
  10     Threading Building Blocks is distributed in the hope that it will be
  11     useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  12     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with Threading Building Blocks; if not, write to the Free Software
  17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19     As a special exception, you may use this file as part of a free software
  20     library without restriction.  Specifically, if other files instantiate
  21     templates or use macros or inline functions from this file, or you compile
  22     this file and link it with other files to produce an executable, this
  23     file does not by itself cause the resulting executable to be covered by
  24     the GNU General Public License.  This exception does not however
  25     invalidate any other reasons why the executable file might be covered by
  26     the GNU General Public License.
  27 */
  28
  29 #ifndef __TBB_task_scheduler_init_H
  30 #define __TBB_task_scheduler_init_H
  31
  32 #include "tbb_stddef.h"
  33 #include "limits.h"
  34
  35 namespace tbb {
  36
  37 typedef std::size_t stack_size_type;
  38
  39 //! @cond INTERNAL
  40 namespace internal {
  41     //! Internal to library. Should not be used by clients.
  42     /** @ingroup task_scheduling */
  43     class scheduler;
  44 } // namespace internal
  45 //! @endcond
  46
  47 //! Class delimiting the scope of task scheduler activity.
  48 /** A thread can construct a task_scheduler_init object and keep it alive
  49     while it uses TBB's tasking subsystem (including parallel algorithms).
  50
  51     This class allows to customize properties of the TBB task pool to some extent.
  52     For example it can limit concurrency level of parallel work initiated by the
  53     given thread. It also can be used to specify stack size of the TBB worker threads,
  54     though this setting is not effective if the thread pool has already been created.
  55
  56     If a parallel construct is used without task_scheduler_init object previously
  57     created, the scheduler will be initialized automatically with default settings,
  58     and will persist until this thread exits. Default concurrency level is defined
  59     as described in task_scheduler_init::initialize().
  60     @ingroup task_scheduling */
  61 class task_scheduler_init: internal::no_copy {
  62 #if TBB_USE_EXCEPTIONS
  63     enum ExceptionPropagationMode {
  64         propagation_mode_exact = 1u,
  65         propagation_mode_captured = 2u,
  66         propagation_mode_mask = propagation_mode_exact | propagation_mode_captured
  67     };
  68 #endif /* TBB_USE_EXCEPTIONS */
  69
  70     /** NULL if not currently initialized. */
  71     internal::scheduler* my_scheduler;
  72 public:
  73
  74     //! Typedef for number of threads that is automatic.
  75     static const int automatic = -1;
  76
  77     //! Argument to initialize() or constructor that causes initialization to be deferred.
  78     static const int deferred = -2;
  79
  80     //! Ensure that scheduler exists for this thread
  81     /** A value of -1 lets TBB decide on the number of threads, which is usually
  82         maximal hardware concurrency for this process, that is the number of logical
  83         CPUs on the machine (possibly limited by the processor affinity mask of this
  84         process (Windows) or of this thread (Linux, FreeBSD). It is preferable option
  85         for production code because it helps to avoid nasty surprises when several
  86         TBB based components run side-by-side or in a nested fashion inside the same
  87         process.
  88
  89         The number_of_threads is ignored if any other task_scheduler_inits
  90         currently exist.  A thread may construct multiple task_scheduler_inits.
  91         Doing so does no harm because the underlying scheduler is reference counted. */
  92     void __TBB_EXPORTED_METHOD initialize( int number_of_threads=automatic );
  93
  94     //! The overloaded method with stack size parameter
  95     /** Overloading is necessary to preserve ABI compatibility */
  96     void __TBB_EXPORTED_METHOD initialize( int number_of_threads, stack_size_type thread_stack_size );
  97
  98     //! Inverse of method initialize.
  99     void __TBB_EXPORTED_METHOD terminate();
 100
 101     //! Shorthand for default constructor followed by call to initialize(number_of_threads).
 102     task_scheduler_init( int number_of_threads=automatic, stack_size_type thread_stack_size=0 ) : my_scheduler(NULL)  {
 103 #if TBB_USE_EXCEPTIONS
 104         // Take two lowest order bits of the stack size argument to communicate
 105         // default exception propagation mode of the client to be used when the
 106         // client manually creates tasks in the master thread and does not use
 107         // explicit task group context object. This is necessary because newer
 108         // TBB binaries with exact propagation enabled by default may be used
 109         // by older clients that expect tbb::captured_exception wrapper.
 110         // All zeros mean old client - no preference.
 111         __TBB_ASSERT( !(thread_stack_size & propagation_mode_mask), "Requested stack size is not aligned" );
 112         thread_stack_size |= TBB_USE_CAPTURED_EXCEPTION ? propagation_mode_captured : propagation_mode_exact;
 113 #endif /* TBB_USE_EXCEPTIONS */
 114         initialize( number_of_threads, thread_stack_size );
 115     }
 116
 117     //! Destroy scheduler for this thread if thread has no other live task_scheduler_inits.
 118     ~task_scheduler_init() {
 119         if( my_scheduler )
 120             terminate();
 121         internal::poison_pointer( my_scheduler );
 122     }
 123     //! Returns the number of threads TBB scheduler would create if initialized by default.
 124     /** Result returned by this method does not depend on whether the scheduler
 125         has already been initialized.
 126
 127         Because tbb 2.0 does not support blocking tasks yet, you may use this method
 128         to boost the number of threads in the tbb's internal pool, if your tasks are
 129         doing I/O operations. The optimal number of additional threads depends on how
 130         much time your tasks spend in the blocked state.
 131
 132         Before TBB 3.0 U4 this method returned the number of logical CPU in the
 133         system. Currently on Windows, Linux and FreeBSD it returns the number of
 134         logical CPUs available to the current process in accordance with its affinity
 135         mask.
 136
 137         NOTE: The return value of this method never changes after its first invocation.
 138         This means that changes in the process affinity mask that took place after
 139         this method was first invoked will not affect the number of worker threads
 140         in the TBB worker threads pool. */
 141     static int __TBB_EXPORTED_FUNC default_num_threads ();
 142
 143     //! Returns true if scheduler is active (initialized); false otherwise
 144     bool is_active() const { return my_scheduler != NULL; }
 145 };
 146
 147 } // namespace tbb
 148
 149 #endif /* __TBB_task_scheduler_init_H */