framework/inc/threadhelp/gate.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: gate.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_THREADHELP_GATE_HXX_
  32 #define __FRAMEWORK_THREADHELP_GATE_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <threadhelp/inoncopyable.h>
  39 #include <threadhelp/igate.h>
  40
  41 //_________________________________________________________________________________________________________________
  42 //      interface includes
  43 //_________________________________________________________________________________________________________________
  44
  45 //_________________________________________________________________________________________________________________
  46 //      other includes
  47 //_________________________________________________________________________________________________________________
  48 #include <osl/mutex.hxx>
  49 #include <osl/conditn.hxx>
  50
  51 //_________________________________________________________________________________________________________________
  52 //      namespace
  53 //_________________________________________________________________________________________________________________
  54
  55 namespace framework{
  56
  57 //_________________________________________________________________________________________________________________
  58 //      const
  59 //_________________________________________________________________________________________________________________
  60
  61 //_________________________________________________________________________________________________________________
  62 //      declarations
  63 //_________________________________________________________________________________________________________________
  64
  65 /*-************************************************************************************************************//**
  66     @short          implement a gate to block multiple threads at same time or unblock all
  67     @descr                      A gate can be used as a negative-condition! You can open a "door" - wait() will not block ...
  68                     or you can close it - wait() blocks till open() is called again.
  69                     As a special feature you can open the gate a little bit by sing openGap().
  70                     Then all currently waiting threads are running immediately - but new ones are blocked!
  71
  72     @attention          To prevent us against wrong using, the default ctor, copy ctor and the =operator are maked private!
  73
  74     @implements     IGate
  75     @base           IGate
  76                     INonCopyable
  77
  78     @devstatus          ready to use
  79 *//*-*************************************************************************************************************/
  80 class Gate : public  IGate
  81            , private INonCopyable
  82 {
  83     //-------------------------------------------------------------------------------------------------------------
  84     //  public methods
  85     //-------------------------------------------------------------------------------------------------------------
  86     public:
  87
  88         /*-****************************************************************************************************//**
  89             @short              ctor
  90             @descr              These initialize the object right as an open gate.
  91
  92             @seealso    -
  93
  94             @param              -
  95             @return             -
  96
  97             @onerror    -
  98         *//*-*****************************************************************************************************/
  99         inline Gate()
 100             :   m_bClosed   ( sal_False )
 101             ,   m_bGapOpen  ( sal_False )
 102         {
 103             open();
 104         }
 105
 106         /*-****************************************************************************************************//**
 107             @short              dtor
 108             @descr              Is user forget it - we open the gate ...
 109                         blocked threads can running ... but I don't know
 110                         if it's right - we are destroyed yet!?
 111
 112             @seealso    -
 113
 114             @param              -
 115             @return             -
 116
 117             @onerror    -
 118         *//*-*****************************************************************************************************/
 119         inline virtual ~Gate()
 120         {
 121             open();
 122         }
 123
 124         /*-****************************************************************************************************//**
 125             @interface  IGate
 126             @short              open the gate
 127             @descr              A wait() call will not block then.
 128
 129             @seealso    method close()
 130
 131             @param              -
 132             @return             -
 133
 134             @onerror    -
 135         *//*-*****************************************************************************************************/
 136         inline virtual void open()
 137         {
 138             // We must safe access to our internal member!
 139             ::osl::MutexGuard aLock( m_aAccessLock );
 140             // Set condition -> wait don't block any longer -> gate is open
 141             m_aPassage.set();
 142             // Check if operation was successful!
 143             // Check returns false if condition isn't set => m_bClosed will be true then => we must return false; opening failed
 144             m_bClosed = ( m_aPassage.check() == sal_False );
 145         }
 146
 147         /*-****************************************************************************************************//**
 148             @interface  IGate
 149             @short              close the gate
 150             @descr              A wait() call will block then.
 151
 152             @seealso    method open()
 153
 154             @param              -
 155             @return             -
 156
 157             @onerror    -
 158         *//*-*****************************************************************************************************/
 159         inline virtual void close()
 160         {
 161             // We must safe access to our internal member!
 162             ::osl::MutexGuard aLock( m_aAccessLock );
 163             // Reset condition -> wait blocks now -> gate is closed
 164             m_aPassage.reset();
 165             // Check if operation was successful!
 166             // Check returns false if condition was reseted => m_bClosed will be true then => we can return true; closing ok
 167             m_bClosed = ( m_aPassage.check() == sal_False );
 168         }
 169
 170         /*-****************************************************************************************************//**
 171             @interface  IGate
 172             @short              open gate for current waiting threads
 173             @descr              All current waiting threads stand in wait() at line "m_aPassage.wait()" ...
 174                         With this call you can open the passage for these waiting ones.
 175                         The "gap" is closed by any new thread which call wait() automaticly!
 176
 177             @seealso    method wait()
 178             @seealso    method open()
 179
 180             @param              -
 181             @return             -
 182
 183             @onerror    -
 184         *//*-*****************************************************************************************************/
 185         inline virtual void openGap()
 186         {
 187             // We must safe access to our internal member!
 188             ::osl::MutexGuard aLock( m_aAccessLock );
 189             // Open passage for current waiting threads.
 190             m_aPassage.set();
 191             // Check state of condition.
 192             // If condition is set check() returns true => m_bGapOpen will be true too => we can use it as return value.
 193             m_bGapOpen = ( m_aPassage.check() == sal_True );
 194         }
 195
 196         /*-****************************************************************************************************//**
 197             @interface  IGate
 198             @short              must be called to pass the gate
 199             @descr              If gate "open"   => wait() will not block.
 200                         If gate "closed" => wait() will block till somewhere open it again.
 201                         If gap  "open"   => currently waiting threads unblocked, new ones blocked
 202
 203             @seealso    method wait()
 204             @seealso    method open()
 205
 206             @param              "pTimeOut", optional parameter to wait a certain time
 207             @return             true, if wait was successful (gate was opened)
 208                         false, if condition has an error or timeout was reached!
 209
 210             @onerror    We return false.
 211         *//*-*****************************************************************************************************/
 212         inline virtual sal_Bool wait( const TimeValue* pTimeOut = NULL )
 213         {
 214             // We must safe access to our internal member!
 215             ::osl::ClearableMutexGuard aLock( m_aAccessLock );
 216             // If gate not closed - caller can pass it.
 217             sal_Bool bSuccessful = sal_True;
 218             if( m_bClosed == sal_True )
 219             {
 220                 // Otherwise first new thread must close an open gap!
 221                 if( m_bGapOpen == sal_True )
 222                 {
 223                     m_bGapOpen = sal_False;
 224                     m_aPassage.reset();
 225                 }
 226                 // Then we must release used access lock -
 227                 // because next call will block ...
 228                 // and if we hold the access lock nobody else can use this object without a dadlock!
 229                 aLock.clear();
 230                 // Wait for opening gate ...
 231                 bSuccessful = ( m_aPassage.wait( pTimeOut ) == ::osl::Condition::result_ok );
 232             }
 233
 234             return bSuccessful;
 235         }
 236
 237     //-------------------------------------------------------------------------------------------------------------
 238     //  private member
 239     //-------------------------------------------------------------------------------------------------------------
 240     private:
 241
 242         ::osl::Mutex            m_aAccessLock   ;
 243         ::osl::Condition        m_aPassage              ;
 244         sal_Bool                        m_bClosed               ;
 245         sal_Bool                        m_bGapOpen              ;
 246
 247 };              //      class Gate
 248
 249 }               //      namespace framework
 250
 251 #endif  //      #ifndef __FRAMEWORK_THREADHELP_GATE_HXX_