include/framework/gate.hxx

   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 #pragma once
  21
  22 #include <mutex>
  23 #include <osl/conditn.hxx>
  24
  25 namespace framework{
  26
  27 /*-************************************************************************************************************
  28     @short          implement a gate to block multiple threads at the same time or unblock all
  29     @descr          A gate can be used as a negative-condition! You can open a "door" - wait() will not block ...
  30                     or you can close it - wait() blocks till open() is called again.
  31                     Then all currently waiting threads are running immediately - but new ones are blocked!
  32
  33     @attention      To prevent us against wrong using, the default ctor, copy ctor and the =operator are marked private!
  34
  35     @devstatus      ready to use
  36 *//*-*************************************************************************************************************/
  37 class Gate
  38 {
  39
  40     //  public methods
  41
  42     public:
  43
  44         /*-****************************************************************************************************
  45             @short      ctor
  46             @descr      These initialize the object right as an open gate.
  47         *//*-*****************************************************************************************************/
  48         Gate()
  49             :   m_bClosed   ( false )
  50         {
  51             open();
  52         }
  53
  54         /*-****************************************************************************************************
  55             @short      dtor
  56             @descr      Is user forget it - we open the gate ...
  57                         blocked threads can running ... but I don't know
  58                         if it's right - we are destroyed yet!?
  59         *//*-*****************************************************************************************************/
  60         ~Gate()
  61         {
  62             open();
  63         }
  64         /*-****************************************************************************************************
  65             @short      copy-ctor
  66             @descr      Forbid copy construction
  67         *//*-*****************************************************************************************************/
  68         Gate(const Gate&) = delete;
  69         /*-****************************************************************************************************
  70             @short      copy-assignment
  71             @descr      Forbid copy assigning
  72         *//*-*****************************************************************************************************/
  73         Gate& operator=(const Gate&) = delete;
  74
  75         /*-****************************************************************************************************
  76             @short      open the gate
  77             @descr      A wait() call will not block then.
  78
  79             @seealso    method close()
  80         *//*-*****************************************************************************************************/
  81         void open()
  82         {
  83             // We must safe access to our internal member!
  84             std::unique_lock aLock( m_aAccessLock );
  85             // Set condition -> wait don't block any longer -> gate is open
  86             m_aPassage.set();
  87             // Check if operation was successful!
  88             // Check returns false if condition isn't set => m_bClosed will be true then => we must return false; opening failed
  89             m_bClosed = !m_aPassage.check();
  90         }
  91
  92         /*-****************************************************************************************************
  93             @short      close the gate
  94             @descr      A wait() call will block then.
  95
  96             @seealso    method open()
  97         *//*-*****************************************************************************************************/
  98         void close()
  99         {
 100             // We must safe access to our internal member!
 101             std::unique_lock aLock( m_aAccessLock );
 102             // Reset condition -> wait blocks now -> gate is closed
 103             m_aPassage.reset();
 104             // Check if operation was successful!
 105             // Check returns false if condition was reset => m_bClosed will be true then => we can return true; closing ok
 106             m_bClosed = !m_aPassage.check();
 107         }
 108
 109         /*-****************************************************************************************************
 110             @short      must be called to pass the gate
 111             @descr      If gate "open"   => wait() will not block.
 112                         If gate "closed" => wait() will block till somewhere open it again.
 113
 114             @seealso    method wait()
 115             @seealso    method open()
 116
 117         *//*-*****************************************************************************************************/
 118         void wait()
 119         {
 120             // We must safe access to our internal member!
 121             std::unique_lock aLock( m_aAccessLock );
 122             // If gate not closed - caller can pass it.
 123             if( m_bClosed )
 124             {
 125                 // Then we must release used access lock -
 126                 // because next call will block...
 127                 // and if we hold the access lock nobody else can use this object without a deadlock!
 128                 aLock.unlock();
 129                 // Wait for opening gate...
 130                 m_aPassage.wait();
 131             }
 132         }
 133
 134     //  private member
 135
 136     private:
 137
 138         std::mutex          m_aAccessLock;
 139         ::osl::Condition    m_aPassage;
 140         bool                m_bClosed;
 141
 142 };      //  class Gate
 143
 144 }       //  namespace framework
 145
 146 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */