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