LCOV - code coverage report
Current view: top level - framework/inc/threadhelp - gate.hxx (source / functions) Hit Total Coverage
Test: libreoffice_filtered.info Lines: 23 33 69.7 %
Date: 2012-08-25 Functions: 5 7 71.4 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 18 52 34.6 %

           Branch data     Line data    Source code
       1                 :            : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
       2                 :            : /*
       3                 :            :  * This file is part of the LibreOffice project.
       4                 :            :  *
       5                 :            :  * This Source Code Form is subject to the terms of the Mozilla Public
       6                 :            :  * License, v. 2.0. If a copy of the MPL was not distributed with this
       7                 :            :  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
       8                 :            :  *
       9                 :            :  * This file incorporates work covered by the following license notice:
      10                 :            :  *
      11                 :            :  *   Licensed to the Apache Software Foundation (ASF) under one or more
      12                 :            :  *   contributor license agreements. See the NOTICE file distributed
      13                 :            :  *   with this work for additional information regarding copyright
      14                 :            :  *   ownership. The ASF licenses this file to you under the Apache
      15                 :            :  *   License, Version 2.0 (the "License"); you may not use this file
      16                 :            :  *   except in compliance with the License. You may obtain a copy of
      17                 :            :  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
      18                 :            :  */
      19                 :            : 
      20                 :            : #ifndef __FRAMEWORK_THREADHELP_GATE_HXX_
      21                 :            : #define __FRAMEWORK_THREADHELP_GATE_HXX_
      22                 :            : 
      23                 :            : #include <threadhelp/inoncopyable.h>
      24                 :            : #include <threadhelp/igate.h>
      25                 :            : 
      26                 :            : #include <osl/mutex.hxx>
      27                 :            : #include <osl/conditn.hxx>
      28                 :            : 
      29                 :            : namespace framework{
      30                 :            : 
      31                 :            : /*-************************************************************************************************************//**
      32                 :            :     @short          implement a gate to block multiple threads at same time or unblock all
      33                 :            :     @descr          A gate can be used as a negative-condition! You can open a "door" - wait() will not block ...
      34                 :            :                     or you can close it - wait() blocks till open() is called again.
      35                 :            :                     As a special feature you can open the gate a little bit by sing openGap().
      36                 :            :                     Then all currently waiting threads are running immediately - but new ones are blocked!
      37                 :            : 
      38                 :            :     @attention      To prevent us against wrong using, the default ctor, copy ctor and the =operator are maked private!
      39                 :            : 
      40                 :            :     @implements     IGate
      41                 :            :     @base           IGate
      42                 :            :                     INonCopyable
      43                 :            : 
      44                 :            :     @devstatus      ready to use
      45                 :            : *//*-*************************************************************************************************************/
      46                 :            : class Gate : public  IGate
      47                 :            :            , private INonCopyable
      48                 :            : {
      49                 :            :     //-------------------------------------------------------------------------------------------------------------
      50                 :            :     //  public methods
      51                 :            :     //-------------------------------------------------------------------------------------------------------------
      52                 :            :     public:
      53                 :            : 
      54                 :            :         /*-****************************************************************************************************//**
      55                 :            :             @short      ctor
      56                 :            :             @descr      These initialize the object right as an open gate.
      57                 :            : 
      58                 :            :             @seealso    -
      59                 :            : 
      60                 :            :             @param      -
      61                 :            :             @return     -
      62                 :            : 
      63                 :            :             @onerror    -
      64                 :            :         *//*-*****************************************************************************************************/
      65                 :       4634 :         inline Gate()
      66                 :            :             :   m_bClosed   ( sal_False )
      67 [ +  - ][ +  - ]:       4634 :             ,   m_bGapOpen  ( sal_False )
      68                 :            :         {
      69         [ +  - ]:       4634 :             open();
      70                 :       4634 :         }
      71                 :            : 
      72                 :            :         /*-****************************************************************************************************//**
      73                 :            :             @short      dtor
      74                 :            :             @descr      Is user forget it - we open the gate ...
      75                 :            :                         blocked threads can running ... but I don't know
      76                 :            :                         if it's right - we are destroyed yet!?
      77                 :            : 
      78                 :            :             @seealso    -
      79                 :            : 
      80                 :            :             @param      -
      81                 :            :             @return     -
      82                 :            : 
      83                 :            :             @onerror    -
      84                 :            :         *//*-*****************************************************************************************************/
      85                 :       4252 :         inline virtual ~Gate()
      86 [ +  - ][ +  - ]:       4252 :         {
      87         [ +  - ]:       4252 :             open();
      88         [ -  + ]:       4252 :         }
      89                 :            : 
      90                 :            :         /*-****************************************************************************************************//**
      91                 :            :             @interface  IGate
      92                 :            :             @short      open the gate
      93                 :            :             @descr      A wait() call will not block then.
      94                 :            : 
      95                 :            :             @seealso    method close()
      96                 :            : 
      97                 :            :             @param      -
      98                 :            :             @return     -
      99                 :            : 
     100                 :            :             @onerror    -
     101                 :            :         *//*-*****************************************************************************************************/
     102                 :     564289 :         inline virtual void open()
     103                 :            :         {
     104                 :            :             // We must safe access to our internal member!
     105         [ +  - ]:     564289 :             ::osl::MutexGuard aLock( m_aAccessLock );
     106                 :            :             // Set condition -> wait don't block any longer -> gate is open
     107         [ +  - ]:     564289 :             m_aPassage.set();
     108                 :            :             // Check if operation was successful!
     109                 :            :             // Check returns false if condition isn't set => m_bClosed will be true then => we must return false; opening failed
     110 [ +  - ][ +  - ]:     564289 :             m_bClosed = ( m_aPassage.check() == sal_False );
     111                 :     564289 :         }
     112                 :            : 
     113                 :            :         /*-****************************************************************************************************//**
     114                 :            :             @interface  IGate
     115                 :            :             @short      close the gate
     116                 :            :             @descr      A wait() call will block then.
     117                 :            : 
     118                 :            :             @seealso    method open()
     119                 :            : 
     120                 :            :             @param      -
     121                 :            :             @return     -
     122                 :            : 
     123                 :            :             @onerror    -
     124                 :            :         *//*-*****************************************************************************************************/
     125                 :     550769 :         inline virtual void close()
     126                 :            :         {
     127                 :            :             // We must safe access to our internal member!
     128         [ +  - ]:     550769 :             ::osl::MutexGuard aLock( m_aAccessLock );
     129                 :            :             // Reset condition -> wait blocks now -> gate is closed
     130         [ +  - ]:     550769 :             m_aPassage.reset();
     131                 :            :             // Check if operation was successful!
     132                 :            :             // Check returns false if condition was reseted => m_bClosed will be true then => we can return true; closing ok
     133 [ +  - ][ +  - ]:     550769 :             m_bClosed = ( m_aPassage.check() == sal_False );
     134                 :     550769 :         }
     135                 :            : 
     136                 :            :         /*-****************************************************************************************************//**
     137                 :            :             @interface  IGate
     138                 :            :             @short      open gate for current waiting threads
     139                 :            :             @descr      All current waiting threads stand in wait() at line "m_aPassage.wait()" ...
     140                 :            :                         With this call you can open the passage for these waiting ones.
     141                 :            :                         The "gap" is closed by any new thread which call wait() automaticly!
     142                 :            : 
     143                 :            :             @seealso    method wait()
     144                 :            :             @seealso    method open()
     145                 :            : 
     146                 :            :             @param      -
     147                 :            :             @return     -
     148                 :            : 
     149                 :            :             @onerror    -
     150                 :            :         *//*-*****************************************************************************************************/
     151                 :          0 :         inline virtual void openGap()
     152                 :            :         {
     153                 :            :             // We must safe access to our internal member!
     154         [ #  # ]:          0 :             ::osl::MutexGuard aLock( m_aAccessLock );
     155                 :            :             // Open passage for current waiting threads.
     156         [ #  # ]:          0 :             m_aPassage.set();
     157                 :            :             // Check state of condition.
     158                 :            :             // If condition is set check() returns true => m_bGapOpen will be true too => we can use it as return value.
     159 [ #  # ][ #  # ]:          0 :             m_bGapOpen = ( m_aPassage.check() == sal_True );
     160                 :          0 :         }
     161                 :            : 
     162                 :            :         /*-****************************************************************************************************//**
     163                 :            :             @interface  IGate
     164                 :            :             @short      must be called to pass the gate
     165                 :            :             @descr      If gate "open"   => wait() will not block.
     166                 :            :                         If gate "closed" => wait() will block till somewhere open it again.
     167                 :            :                         If gap  "open"   => currently waiting threads unblocked, new ones blocked
     168                 :            : 
     169                 :            :             @seealso    method wait()
     170                 :            :             @seealso    method open()
     171                 :            : 
     172                 :            :             @param      "pTimeOut", optional parameter to wait a certain time
     173                 :            :             @return     true, if wait was successful (gate was opened)
     174                 :            :                         false, if condition has an error or timeout was reached!
     175                 :            : 
     176                 :            :             @onerror    We return false.
     177                 :            :         *//*-*****************************************************************************************************/
     178                 :       4336 :         inline virtual sal_Bool wait( const TimeValue* pTimeOut = NULL )
     179                 :            :         {
     180                 :            :             // We must safe access to our internal member!
     181         [ +  - ]:       4336 :             ::osl::ClearableMutexGuard aLock( m_aAccessLock );
     182                 :            :             // If gate not closed - caller can pass it.
     183                 :       4336 :             sal_Bool bSuccessful = sal_True;
     184         [ -  + ]:       4336 :             if( m_bClosed == sal_True )
     185                 :            :             {
     186                 :            :                 // Otherwise first new thread must close an open gap!
     187         [ #  # ]:          0 :                 if( m_bGapOpen == sal_True )
     188                 :            :                 {
     189                 :          0 :                     m_bGapOpen = sal_False;
     190         [ #  # ]:          0 :                     m_aPassage.reset();
     191                 :            :                 }
     192                 :            :                 // Then we must release used access lock -
     193                 :            :                 // because next call will block ...
     194                 :            :                 // and if we hold the access lock nobody else can use this object without a dadlock!
     195         [ #  # ]:          0 :                 aLock.clear();
     196                 :            :                 // Wait for opening gate ...
     197         [ #  # ]:          0 :                 bSuccessful = ( m_aPassage.wait( pTimeOut ) == ::osl::Condition::result_ok );
     198                 :            :             }
     199                 :            : 
     200         [ +  - ]:       4336 :             return bSuccessful;
     201                 :            :         }
     202                 :            : 
     203                 :            :     //-------------------------------------------------------------------------------------------------------------
     204                 :            :     //  private member
     205                 :            :     //-------------------------------------------------------------------------------------------------------------
     206                 :            :     private:
     207                 :            : 
     208                 :            :         ::osl::Mutex        m_aAccessLock   ;
     209                 :            :         ::osl::Condition    m_aPassage      ;
     210                 :            :         sal_Bool            m_bClosed       ;
     211                 :            :         sal_Bool            m_bGapOpen      ;
     212                 :            : 
     213                 :            : };      //  class Gate
     214                 :            : 
     215                 :            : }       //  namespace framework
     216                 :            : 
     217                 :            : #endif  //  #ifndef __FRAMEWORK_THREADHELP_GATE_HXX_
     218                 :            : 
     219                 :            : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10