1 /* 2 Copyright (c) 2005-2021 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 #include "detail/_namespace_injection.h" 21 #include "task_arena.h" 22 #include <atomic> 23 24 namespace tbb { 25 namespace detail { 26 27 namespace d1 { 28 class task_scheduler_observer; 29 } 30 31 namespace r1 { 32 class observer_proxy; 33 class observer_list; 34 35 //! Enable or disable observation 36 /** For local observers the method can be used only when the current thread 37 has the task scheduler initialized or is attached to an arena. 38 Repeated calls with the same state are no-ops. **/ 39 TBB_EXPORT void __TBB_EXPORTED_FUNC observe(d1::task_scheduler_observer&, bool state = true); 40 } 41 42 namespace d1 { 43 class task_scheduler_observer { 44 friend class r1::observer_proxy; 45 friend class r1::observer_list; 46 friend void r1::observe(d1::task_scheduler_observer&, bool); 47 48 //! Pointer to the proxy holding this observer. 49 /** Observers are proxied by the scheduler to maintain persistent lists of them. **/ 50 std::atomic<r1::observer_proxy*> my_proxy{ nullptr }; 51 52 //! Counter preventing the observer from being destroyed while in use by the scheduler. 53 /** Valid only when observation is on. **/ 54 std::atomic<intptr_t> my_busy_count{ 0 }; 55 56 //! Contains task_arena pointer 57 task_arena* my_task_arena{ nullptr }; 58 public: 59 //! Returns true if observation is enabled, false otherwise. is_observing()60 bool is_observing() const { return my_proxy.load(std::memory_order_relaxed) != nullptr; } 61 62 //! Entry notification 63 /** Invoked from inside observe(true) call and whenever a worker enters the arena 64 this observer is associated with. If a thread is already in the arena when 65 the observer is activated, the entry notification is called before it 66 executes the first stolen task. **/ on_scheduler_entry(bool)67 virtual void on_scheduler_entry( bool /*is_worker*/ ) {} 68 69 //! Exit notification 70 /** Invoked from inside observe(false) call and whenever a worker leaves the 71 arena this observer is associated with. **/ on_scheduler_exit(bool)72 virtual void on_scheduler_exit( bool /*is_worker*/ ) {} 73 74 //! Construct local or global observer in inactive state (observation disabled). 75 /** For a local observer entry/exit notifications are invoked whenever a worker 76 thread joins/leaves the arena of the observer's owner thread. If a thread is 77 already in the arena when the observer is activated, the entry notification is 78 called before it executes the first stolen task. **/ 79 explicit task_scheduler_observer() = default; 80 81 //! Construct local observer for a given arena in inactive state (observation disabled). 82 /** entry/exit notifications are invoked whenever a thread joins/leaves arena. 83 If a thread is already in the arena when the observer is activated, the entry notification 84 is called before it executes the first stolen task. **/ task_scheduler_observer(task_arena & a)85 explicit task_scheduler_observer(task_arena& a) : my_task_arena(&a) {} 86 87 /** Destructor protects instance of the observer from concurrent notification. 88 It is recommended to disable observation before destructor of a derived class starts, 89 otherwise it can lead to concurrent notification callback on partly destroyed object **/ ~task_scheduler_observer()90 virtual ~task_scheduler_observer() { 91 if (my_proxy.load(std::memory_order_acquire)) { 92 observe(false); 93 } 94 } 95 96 //! Enable or disable observation 97 /** Warning: concurrent invocations of this method are not safe. 98 Repeated calls with the same state are no-ops. **/ 99 void observe(bool state = true) { 100 if( state && !my_proxy.load(std::memory_order_relaxed) ) { 101 __TBB_ASSERT( my_busy_count.load(std::memory_order_relaxed) == 0, "Inconsistent state of task_scheduler_observer instance"); 102 } 103 r1::observe(*this, state); 104 } 105 }; 106 107 } // namespace d1 108 } // namespace detail 109 110 inline namespace v1 { 111 using detail::d1::task_scheduler_observer; 112 } 113 } // namespace tbb 114 115 116 #endif /* __TBB_task_scheduler_observer_H */ 117