dali/devel-api/threading/conditional-wait.h

   1 #ifndef DALI_CONDITIONAL_WAIT_H
   2 #define DALI_CONDITIONAL_WAIT_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/common/dali-common.h>
  23
  24 namespace Dali
  25 {
  26 /**
  27  * Helper class to allow conditional waiting and notifications between multiple threads.
  28  */
  29 class DALI_CORE_API ConditionalWait
  30 {
  31 public:
  32   /**
  33    * @brief Allows client code to synchronize updates to its own state with the
  34    * internal state of a ConditionalWait object.
  35    */
  36   class DALI_CORE_API ScopedLock
  37   {
  38   public:
  39     /**
  40      * Constructor
  41      * @brief Will acquire the internal mutex of the ConditionalWait object passed in.
  42      * @param[in] wait The ConditionalWait object to lock.
  43      */
  44     ScopedLock(ConditionalWait& wait);
  45
  46     /**
  47      * Destructor
  48      * @brief Will release the internal mutex of the ConditionalWait object passed in.
  49      */
  50     ~ScopedLock();
  51
  52     /**
  53      * Getter for the ConditionalWait locked for this instance's lifetime.
  54      * @return the ConditionalWait object currently locked.
  55      */
  56     ConditionalWait& GetLockedWait() const;
  57
  58   public: // Data, public to allow nesting class to access
  59     struct ScopedLockImpl;
  60     ScopedLockImpl* mImpl;
  61
  62   private:
  63     // Not implemented as ScopedLock cannot be copied:
  64     ScopedLock(const ScopedLock&);
  65     const ScopedLock& operator=(const ScopedLock&);
  66   };
  67
  68   /**
  69    * @brief Constructor, creates the internal synchronization objects
  70    */
  71   ConditionalWait();
  72
  73   /**
  74    * @brief Destructor, non-virtual as this is not a base class
  75    */
  76   ~ConditionalWait();
  77
  78   /**
  79    * @brief Notifies another thread to continue if it is blocked on a wait.
  80    *
  81    * Can be called from any thread.
  82    * Does not block the current thread but may cause a rescheduling of threads.
  83    */
  84   void Notify();
  85
  86   /**
  87    * @brief Notifies another thread to continue if it is blocked on a wait.
  88    *
  89    * Assumes that the ScopedLock object passed in has already locked the internal state of
  90    * this object.
  91    * Can be called from any thread.
  92    * Does not block the current thread but may cause a rescheduling of threads.
  93    *
  94    * @param[in] scope A pre-existing lock on the internal state of this object.
  95    */
  96   void Notify(const ScopedLock& scope);
  97
  98   /**
  99    * @brief Wait for another thread to notify us when the condition is true and we can continue
 100    *
 101    * Will always block current thread until Notify is called
 102    */
 103   void Wait();
 104
 105   /**
 106    * @brief Wait for another thread to notify us when the condition is true and we can continue
 107    *
 108    * Will always block current thread until Notify is called.
 109    * Assumes that the ScopedLock object passed in has already locked the internal state of
 110    * this object. Releases the lock while waiting and re-acquires it when returning
 111    * from the wait.
 112    * @param[in] scope A pre-existing lock on the internal state of this object.
 113    * @pre scope must have been passed this ConditionalWait during its construction.
 114    */
 115   void Wait(const ScopedLock& scope);
 116
 117   /**
 118    * @brief Return the count of threads waiting for this conditional
 119    * @return count of waits
 120    */
 121   unsigned int GetWaitCount() const;
 122
 123 private:
 124   // Not implemented as ConditionalWait is not copyable
 125   ConditionalWait(const ConditionalWait&);
 126   const ConditionalWait& operator=(const ConditionalWait&);
 127
 128   struct ConditionalWaitImpl;
 129   ConditionalWaitImpl* mImpl;
 130 };
 131
 132 } // namespace Dali
 133
 134 #endif // DALI_CONDITIONAL_WAIT_H