inc/FBaseRtWaitingLoop.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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 /*
  18  * @file        FBaseRtWaitingLoop.h
  19  * @brief       This is the header file for the %WaitingLoop class.
  20  *
  21  * This file contains the declarations of the %WaitingLoop class.
  22  */
  23
  24 #ifndef _FBASE_RT_WAITING_LOOP_H_
  25 #define _FBASE_RT_WAITING_LOOP_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseRtIWaitingLoopCondition.h>
  29
  30 namespace Tizen { namespace Base { namespace Runtime
  31 {
  32
  33 class IWaitingLoopCondition;
  34 /*
  35  * @class WaitingLoop
  36  * @brief This class allows developers to make the current thread wait for callback events. This class should be used only for test codes and not for commercial applications.
  37  * @since 2.0
  38  *
  39  * @final This class is not intended for extension.
  40  */
  41 class _OSP_EXPORT_ WaitingLoop
  42         : public Tizen::Base::Object
  43 {
  44 public:
  45         /*
  46          * Gets a pointer to the %WaitingLoop instance.
  47          *
  48          * @since 2.0
  49          *
  50          * @return      A pointer to a WaitingLoop instance, @n
  51          *                              else @c null if it fails
  52          * @remarks  Once the WaitingLoop instance has been created, the instance between the threads must not be used. @n
  53          *                              Especially, the methods that are waiting should be called on the thread where the instance is obtained for the first time.
  54          */
  55         static WaitingLoop* GetInstance(void);
  56
  57         /*
  58          * Starts the waiting loop and waits until the time is expired.
  59          *
  60          * @since 2.0
  61          *
  62          * @param[in] timeout                   The timeout period in milliseconds
  63          * @exception E_SUCCESS                 The method is successful.
  64          * @exception E_TIMEOUT                 The time has expired.
  65          * @exception E_INVALID_STATE   The waiting loop has already been waiting on a callback event. @n
  66          *                                                              In order to wait again, quit the waiting loop.
  67          * @remarks The timeout is set to min(timeout, maximum), where the maximum is set using SetMaxTimeoutForWaiting().
  68          * @see Notify()
  69          */
  70         result Wait(int timeout);
  71
  72         /*
  73          * Starts the waiting loop and waits until the specified condition is met.
  74          *
  75          * @since 2.0
  76          *
  77          * @param[in] condition                 The expiring condition
  78      * @exception E_SUCCESS             The method is successful.
  79      * @exception E_INVALID_STATE   The waiting loop has already been waiting on a callback event. @n
  80          *                                                              In order to wait again, quit the waiting loop.
  81      * @remarks In order to use this method correctly, you have to implement a class inheriting from IWaitingLoopCondition.
  82          */
  83         result Wait(IWaitingLoopCondition& condition);
  84
  85         /*
  86          * Starts the waiting loop and waits until either the expiring condition occurs or the time expires.
  87          *
  88          * @since 2.0
  89          *
  90          * @param[in] timeout                   The timeout period in milliseconds
  91          * @param[in] condition                 The expiring condition
  92          * @exception E_TIMEOUT                 The time has expired.
  93          * @exception E_INVALID_STATE   The waiting loop is waiting on a thread. @n
  94          *                                                              In order to wait again, quit the waiting loop.
  95          * @remarks If the timeout has crossed the maximum value, the expired time goes along with the maximum timeout. @n
  96          *                        In order to use this method correctly, implement a class inheriting from the IWaitingLoopCondition interface
  97          */
  98         result Wait(int timeout, IWaitingLoopCondition& condition);
  99
 100         /*
 101          * Notifies the waiting thread that the related callback has completed the job.
 102          *
 103          * @since 2.0
 104          *
 105          * @remarks This method is recommended when the waiting condition is not explicitly specified by Wait().
 106          */
 107         void Notify(void);
 108
 109         /*
 110          * Sets the maximum timeout for waiting.
 111          *
 112          * @since 2.0
 113          *
 114          * @param[in] timeout    The timeout period in milliseconds
 115          *                                              else @c false
 116          * @remarks If the timeout is considered as a small number, it is replaced with the specified number provided by the platform.
 117          */
 118         static void SetMaxTimeoutForWaiting(int timeout);
 119
 120 private:
 121         //
 122         // This default constructor is intentionally declared as private to implement the %Singleton semantic.
 123         //
 124         // @since 2.0
 125         //
 126         WaitingLoop(void);
 127
 128         //
 129         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 130         //
 131         // @since 2.0
 132         //
 133         WaitingLoop(const WaitingLoop& rhs);
 134
 135         //
 136         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 137         //
 138         // @since 2.0
 139         //
 140         WaitingLoop& operator =(const WaitingLoop& rhs);
 141
 142         //
 143         // This destructor is intentionally declared as private to implement the %Singleton semantic.
 144         //
 145         // @since 2.0
 146         //
 147         virtual ~WaitingLoop(void);
 148
 149         friend class _WaitingLoopImpl;
 150         class _WaitingLoopImpl* __pWaitingLoopImpl;
 151 }; // WaitingLoop
 152
 153 } } } // Tizen::Base::Runtime
 154
 155 #endif // _FBASE_RT_WAITING_LOOP_H_