include/osl/conditn.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 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_OSL_CONDITN_HXX
  25 #define INCLUDED_OSL_CONDITN_HXX
  26
  27 #include "sal/config.h"
  28
  29 #include <cstddef>
  30
  31 #include "osl/time.h"
  32 #include "osl/conditn.h"
  33
  34 #if defined(MACOSX) && defined(__ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES)
  35 #   if __ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES == 1
  36 #       undef check
  37 #   endif
  38 #endif
  39
  40 namespace osl
  41 {
  42     /** Condition variable
  43
  44        A condition variable is essentially an object that is initially
  45        cleared which a thread waits on until it is "set". It allows a
  46        thread to synchronize execution by allowing other threads to wait
  47        for the condition to change before that thread then continues
  48        execution.
  49
  50        @deprecated use C++11's std::condition_variable instead
  51             for a more robust and helpful condition.
  52
  53        @attention Warning: the Condition abstraction is inadequate for
  54             any situation where there may be multiple threads setting,
  55             waiting, and resetting the same condition. It can only be
  56             used to synchronise interactions between two threads
  57             cf. lost wakeups in http://www.cs.wustl.edu/~schmidt/win32-cv-1.html
  58     */
  59     class Condition
  60     {
  61     public:
  62         enum Result
  63         {
  64             result_ok      = osl_cond_result_ok,        /*!< Successful completion.                         */
  65             result_error   = osl_cond_result_error,     /*!< Error occurred. @see osl_getLastSocketError() */
  66             result_timeout = osl_cond_result_timeout    /*!< Blocking operation timed out.                 */
  67         };
  68
  69         /** Create a condition.
  70
  71             @deprecated use C++11's std::condition_variable instead
  72                 for a more robust and helpful condition.
  73         */
  74         Condition()
  75         {
  76             condition = osl_createCondition();
  77         }
  78
  79         /** Release the OS-structures and free condition data-structure.
  80
  81             @deprecated use C++11's std::condition_variable instead
  82                 for a more robust and helpful condition.
  83         */
  84         ~Condition()
  85         {
  86             osl_destroyCondition(condition);
  87         }
  88
  89         /** Release all waiting threads, check returns true.
  90
  91             @deprecated use C++11's std::condition_variable instead
  92                 for a more robust and helpful condition.
  93         */
  94         void set()
  95         {
  96             osl_setCondition(condition);
  97         }
  98
  99         /** Reset condition to false: wait() will block, check() returns
 100             false.
 101
 102             @deprecated use C++11's std::condition_variable instead
 103                         for a more robust and helpful condition.
 104         */
 105         void reset() {
 106             osl_resetCondition(condition);
 107         }
 108
 109         /** Blocks the calling thread until condition is set.
 110
 111             @param [in] pTimeout Timeout to wait before ending the condition.
 112                 Defaults to NULL
 113
 114             @retval result_ok       finished successfully
 115             @retval result_error    error occurred
 116             @retval result_timeout  timed out
 117
 118             @deprecated use C++11's std::condition_variable instead
 119                 for a more robust and helpful condition.
 120         */
 121         Result wait(const TimeValue *pTimeout = NULL)
 122         {
 123             return static_cast<Result>(osl_waitCondition(condition, pTimeout));
 124         }
 125
 126 #if defined LIBO_INTERNAL_ONLY
 127         Result wait(TimeValue const & timeout) { return wait(&timeout); }
 128 #endif
 129
 130         /** Checks if the condition is set without blocking.
 131
 132             @retval true   condition is set
 133             @retval false  condition is not set
 134
 135             @deprecated use C++11's std::condition_variable instead
 136                 for a more robust and helpful condition.
 137         */
 138         bool check()
 139         {
 140             return osl_checkCondition(condition);
 141         }
 142
 143
 144     private:
 145         oslCondition condition;     /*< condition variable */
 146
 147         /** Copy constructor
 148
 149             The underlying oslCondition has no reference count.
 150
 151             Since the underlying oslCondition is not a reference counted
 152             object, copy constructed Condition may work on an already
 153             destructed oslCondition object.
 154
 155             @deprecated use C++11's std::condition_variable instead
 156                 for a more robust and helpful condition.
 157         */
 158         Condition(const Condition& condition) SAL_DELETED_FUNCTION;
 159
 160         /** This assignment operator is deleted for the same reason as
 161             the copy constructor.
 162
 163             @deprecated use C++11's std::condition_variable instead
 164                 for a more robust and helpful condition.
 165         */
 166         Condition& operator= (const Condition&) SAL_DELETED_FUNCTION;
 167     };
 168 }
 169
 170 #endif // INCLUDED_OSL_CONDITN_HXX
 171
 172 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */