include/tbb/task_scheduler_observer.h

   1 /*
   2     Copyright (c) 2005-2019 Intel Corporation
   3
   4     Licensed under the Apache License, Version 2.0 (the "License");
   5     you may not use this file except in compliance with the License.
   6     You may obtain a copy of the License at
   7
   8         http://www.apache.org/licenses/LICENSE-2.0
   9
  10     Unless required by applicable law or agreed to in writing, software
  11     distributed under the License is distributed on an "AS IS" BASIS,
  12     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13     See the License for the specific language governing permissions and
  14     limitations under the License.
  15 */
  16
  17 #ifndef __TBB_task_scheduler_observer_H
  18 #define __TBB_task_scheduler_observer_H
  19
  20 #define __TBB_task_scheduler_observer_H_include_area
  21 #include "internal/_warning_suppress_enable_notice.h"
  22
  23 #include "atomic.h"
  24 #if __TBB_ARENA_OBSERVER
  25 #include "task_arena.h"
  26 #endif
  27
  28 #if __TBB_SCHEDULER_OBSERVER
  29
  30 namespace tbb {
  31 namespace interface6 {
  32 class task_scheduler_observer;
  33 }
  34 namespace internal {
  35
  36 class observer_proxy;
  37 class observer_list;
  38
  39 class task_scheduler_observer_v3 {
  40     friend class observer_proxy;
  41     friend class observer_list;
  42     friend class interface6::task_scheduler_observer;
  43
  44     //! Pointer to the proxy holding this observer.
  45     /** Observers are proxied by the scheduler to maintain persistent lists of them. **/
  46     observer_proxy* my_proxy;
  47
  48     //! Counter preventing the observer from being destroyed while in use by the scheduler.
  49     /** Valid only when observation is on. **/
  50     atomic<intptr_t> my_busy_count;
  51
  52 public:
  53     //! Enable or disable observation
  54     /** For local observers the method can be used only when the current thread
  55         has the task scheduler initialized or is attached to an arena.
  56
  57         Repeated calls with the same state are no-ops. **/
  58     void __TBB_EXPORTED_METHOD observe( bool state=true );
  59
  60     //! Returns true if observation is enabled, false otherwise.
  61     bool is_observing() const {return my_proxy!=NULL;}
  62
  63     //! Construct observer with observation disabled.
  64     task_scheduler_observer_v3() : my_proxy(NULL) { my_busy_count.store<relaxed>(0); }
  65
  66     //! Entry notification
  67     /** Invoked from inside observe(true) call and whenever a worker enters the arena
  68         this observer is associated with. If a thread is already in the arena when
  69         the observer is activated, the entry notification is called before it
  70         executes the first stolen task.
  71
  72         Obsolete semantics. For global observers it is called by a thread before
  73         the first steal since observation became enabled. **/
  74     virtual void on_scheduler_entry( bool /*is_worker*/ ) {}
  75
  76     //! Exit notification
  77     /** Invoked from inside observe(false) call and whenever a worker leaves the
  78         arena this observer is associated with.
  79
  80         Obsolete semantics. For global observers it is called by a thread before
  81         the first steal since observation became enabled. **/
  82     virtual void on_scheduler_exit( bool /*is_worker*/ ) {}
  83
  84     //! Destructor automatically switches observation off if it is enabled.
  85     virtual ~task_scheduler_observer_v3() { if(my_proxy) observe(false);}
  86 };
  87
  88 } // namespace internal
  89
  90 #if __TBB_ARENA_OBSERVER
  91 namespace interface6 {
  92 class task_scheduler_observer : public internal::task_scheduler_observer_v3 {
  93     friend class internal::task_scheduler_observer_v3;
  94     friend class internal::observer_proxy;
  95     friend class internal::observer_list;
  96
  97     /** Negative numbers with the largest absolute value to minimize probability
  98         of coincidence in case of a bug in busy count usage. **/
  99     // TODO: take more high bits for version number
 100     static const intptr_t v6_trait = (intptr_t)((~(uintptr_t)0 >> 1) + 1);
 101
 102     //! contains task_arena pointer or tag indicating local or global semantics of the observer
 103     intptr_t my_context_tag;
 104     enum { global_tag = 0, implicit_tag = 1 };
 105
 106 public:
 107     //! Construct local or global observer in inactive state (observation disabled).
 108     /** For a local observer entry/exit notifications are invoked whenever a worker
 109         thread joins/leaves the arena of the observer's owner thread. If a thread is
 110         already in the arena when the observer is activated, the entry notification is
 111         called before it executes the first stolen task. **/
 112     /** TODO: Obsolete.
 113         Global observer semantics is obsolete as it violates master thread isolation
 114         guarantees and is not composable. Thus the current default behavior of the
 115         constructor is obsolete too and will be changed in one of the future versions
 116         of the library. **/
 117     explicit task_scheduler_observer( bool local = false ) {
 118 #if  __TBB_ARENA_OBSERVER
 119         my_context_tag = local? implicit_tag : global_tag;
 120 #else
 121         __TBB_ASSERT_EX( !local, NULL );
 122         my_context_tag = global_tag;
 123 #endif
 124     }
 125
 126 #if  __TBB_ARENA_OBSERVER
 127     //! Construct local observer for a given arena in inactive state (observation disabled).
 128     /** entry/exit notifications are invoked whenever a thread joins/leaves arena.
 129         If a thread is already in the arena when the observer is activated, the entry notification
 130         is called before it executes the first stolen task. **/
 131     explicit task_scheduler_observer( task_arena & a) {
 132         my_context_tag = (intptr_t)&a;
 133     }
 134 #endif /* __TBB_ARENA_OBSERVER */
 135
 136     /** Destructor protects instance of the observer from concurrent notification.
 137        It is recommended to disable observation before destructor of a derived class starts,
 138        otherwise it can lead to concurrent notification callback on partly destroyed object **/
 139     virtual ~task_scheduler_observer() { if(my_proxy) observe(false); }
 140
 141     //! Enable or disable observation
 142     /** Warning: concurrent invocations of this method are not safe.
 143         Repeated calls with the same state are no-ops. **/
 144     void observe( bool state=true ) {
 145         if( state && !my_proxy ) {
 146             __TBB_ASSERT( !my_busy_count, "Inconsistent state of task_scheduler_observer instance");
 147             my_busy_count.store<relaxed>(v6_trait);
 148         }
 149         internal::task_scheduler_observer_v3::observe(state);
 150     }
 151 };
 152
 153 } //namespace interface6
 154 using interface6::task_scheduler_observer;
 155 #else /*__TBB_ARENA_OBSERVER*/
 156 typedef tbb::internal::task_scheduler_observer_v3 task_scheduler_observer;
 157 #endif /*__TBB_ARENA_OBSERVER*/
 158
 159 } // namespace tbb
 160
 161 #endif /* __TBB_SCHEDULER_OBSERVER */
 162
 163 #include "internal/_warning_suppress_disable_notice.h"
 164 #undef __TBB_task_scheduler_observer_H_include_area
 165
 166 #endif /* __TBB_task_scheduler_observer_H */