inc/FBaseRtWaitingLoop.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /*
  19  * @file        FBaseRtWaitingLoop.h
  20  * @brief       This is the header file for the %WaitingLoop class.
  21  *
  22  * This file contains the declarations of the %WaitingLoop class.
  23  */
  24
  25 #ifndef _FBASE_RT_WAITING_LOOP_H_
  26 #define _FBASE_RT_WAITING_LOOP_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseRtIWaitingLoopCondition.h>
  30
  31 namespace Tizen { namespace Base { namespace Runtime
  32 {
  33
  34 class IWaitingLoopCondition;
  35 /*
  36  * @class WaitingLoop
  37  * @brief This class allows developers to make the current thread wait for callback events. This class should be used only for test codes and don't use this class for commercial applications
  38  * @since 2.0
  39  *
  40  * @final This class is not intended for extension.
  41  */
  42 class _OSP_EXPORT_ WaitingLoop
  43         : public Tizen::Base::Object
  44 {
  45 public:
  46         /*
  47          * Gets the WaitingLoop instance.
  48          *
  49          * @since 2.0
  50          *
  51          * @return      A pointer to the WaitingLoop instance, @n
  52          *                              else @c null if it fails
  53          * @remarks Once the WaitingLoop instance has been created, you must not use the instance between threads. Especially, the methods for waiting should be called on the thread you get the instance at 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 is expired.
  65          * @exception E_INVALID_STATE    The waiting loop has already been waiting on a callback event. In order to wait again, you must quit the waiting loop.
  66          * @remarks The timeout set to min(timeout, maximum), where the maximum is set using SetMaxTimeoutForWaiting().
  67          * @see Notify()
  68          * @see SetMaxTimoutForWaiting()
  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. In order to wait again, you must quit the waiting loop.
  80          * @remarks In order to use this method correctly, you have to implement a class inheriting from %IWaitingLoopCondition.
  81          */
  82         result Wait(IWaitingLoopCondition& condition);
  83
  84         /*
  85          * Starts the waiting loop and waits until either the expiring condition occurs or the time is expired.
  86          *
  87          * @since 2.0
  88          *
  89          * @param[in] timeout   The timeout period in milliseconds
  90          * @param[in] condition The expiring condition
  91          * @exception E_TIMEOUT    The time is expired.
  92          * @exception E_INVALID_STATE    The waiting loop is waiting on a thread. In order to wait again, you must quit the waiting loop.
  93          * @remarks If the timeout is over the maximum, the expired time goes together with the maximum timeout. In order to use this method correctly, you have to implement a class inheriting from %IWaitingLoopCondition interface
  94          */
  95         result Wait(int timeout, IWaitingLoopCondition& condition);
  96
  97         /*
  98          * Notify the waiting thread that the related callback has completed the job.
  99          *
 100          * @since 2.0
 101          *
 102          * @remarks This method is recommended to use when the waiting condition is not explicitly specified with Wait().
 103          */
 104         void Notify(void);
 105
 106         /*
 107          * Sets the maximum timeout for waiting.
 108          *
 109          * @since 2.0
 110          *
 111          * @param[in] timeout    The timeout period in milliseconds
 112          *                              else @c false
 113          * @remarks If the timeout is considered as a small number, it will be replaced with the specified number provided by platform.
 114          */
 115         static void SetMaxTimeoutForWaiting(int timeout);
 116
 117 private:
 118         //
 119         // This default constructor is intentionally declared as private to implement the %Singleton semantic.
 120         //
 121         // @since 2.0
 122         //
 123         WaitingLoop(void);
 124
 125         //
 126         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 127         //
 128         // @since 2.0
 129         //
 130         WaitingLoop(const WaitingLoop& rhs);
 131
 132         //
 133         // The implementation of this copy assignment operator is intentionally blank and delcared as private to prohibit copying of objects.
 134         //
 135         // @since 2.0
 136         //
 137         WaitingLoop& operator =(const WaitingLoop& rhs);
 138
 139         //
 140         // This destructor is intentionally declared as private to implement the %Singleton semantic.
 141         //
 142         // @since 2.0
 143         //
 144         virtual ~WaitingLoop(void);
 145
 146         friend class _WaitingLoopImpl;
 147         class _WaitingLoopImpl* __pWaitingLoopImpl;
 148 }; // WaitingLoop
 149
 150 } } } // Tizen::Base::Runtime
 151
 152 #endif // _FBASE_RT_WAITING_LOOP_H_