thrift/concurrency/Monitor.h

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one
0003  * or more contributor license agreements. See the NOTICE file
0004  * distributed with this work for additional information
0005  * regarding copyright ownership. The ASF licenses this file
0006  * to you under the Apache License, Version 2.0 (the
0007  * "License"); you may not use this file except in compliance
0008  * with the License. You may obtain a copy of the License at
0009  *
0010  *   http://www.apache.org/licenses/LICENSE-2.0
0011  *
0012  * Unless required by applicable law or agreed to in writing,
0013  * software distributed under the License is distributed on an
0014  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0015  * KIND, either express or implied. See the License for the
0016  * specific language governing permissions and limitations
0017  * under the License.
0018  */
0019
0020 #ifndef _THRIFT_CONCURRENCY_MONITOR_H_
0021 #define _THRIFT_CONCURRENCY_MONITOR_H_ 1
0022
0023 #include <chrono>
0024 #include <thrift/concurrency/Exception.h>
0025 #include <thrift/concurrency/Mutex.h>
0026 #include <thrift/TNonCopyable.h>
0027
0028 namespace apache {
0029 namespace thrift {
0030 namespace concurrency {
0031
0032 /**
0033  * A monitor is a combination mutex and condition-event.  Waiting and
0034  * notifying condition events requires that the caller own the mutex.  Mutex
0035  * lock and unlock operations can be performed independently of condition
0036  * events.  This is more or less analogous to java.lang.Object multi-thread
0037  * operations.
0038  *
0039  * Note the Monitor can create a new, internal mutex; alternatively, a
0040  * separate Mutex can be passed in and the Monitor will re-use it without
0041  * taking ownership.  It's the user's responsibility to make sure that the
0042  * Mutex is not deallocated before the Monitor.
0043  *
0044  * Note that all methods are const.  Monitors implement logical constness, not
0045  * bit constness.  This allows const methods to call monitor methods without
0046  * needing to cast away constness or change to non-const signatures.
0047  *
0048  * @version $Id:$
0049  */
0050 class Monitor : apache::thrift::TNonCopyable {
0051 public:
0052   /** Creates a new mutex, and takes ownership of it. */
0053   Monitor();
0054
0055   /** Uses the provided mutex without taking ownership. */
0056   explicit Monitor(Mutex* mutex);
0057
0058   /** Uses the mutex inside the provided Monitor without taking ownership. */
0059   explicit Monitor(Monitor* monitor);
0060
0061   /** Deallocates the mutex only if we own it. */
0062   virtual ~Monitor();
0063
0064   Mutex& mutex() const;
0065
0066   virtual void lock() const;
0067
0068   virtual void unlock() const;
0069
0070   /**
0071    * Waits a maximum of the specified timeout in milliseconds for the condition
0072    * to occur, or waits forever if timeout is zero.
0073    *
0074    * Returns 0 if condition occurs, THRIFT_ETIMEDOUT on timeout, or an error code.
0075    */
0076   int waitForTimeRelative(const std::chrono::milliseconds &timeout) const;
0077
0078   int waitForTimeRelative(uint64_t timeout_ms) const { return waitForTimeRelative(std::chrono::milliseconds(timeout_ms)); }
0079
0080   /**
0081    * Waits until the absolute time specified by abstime.
0082    * Returns 0 if condition occurs, THRIFT_ETIMEDOUT on timeout, or an error code.
0083    */
0084   int waitForTime(const std::chrono::time_point<std::chrono::steady_clock>& abstime) const;
0085
0086   /**
0087    * Waits forever until the condition occurs.
0088    * Returns 0 if condition occurs, or an error code otherwise.
0089    */
0090   int waitForever() const;
0091
0092   /**
0093    * Exception-throwing version of waitForTimeRelative(), called simply
0094    * wait(std::chrono::milliseconds) for historical reasons.  Timeout is in milliseconds.
0095    *
0096    * If the condition occurs, this function returns cleanly; on timeout or
0097    * error an exception is thrown.
0098    */
0099   void wait(const std::chrono::milliseconds &timeout) const;
0100
0101   void wait(uint64_t timeout_ms = 0ULL) const { this->wait(std::chrono::milliseconds(timeout_ms)); }
0102
0103   /** Wakes up one thread waiting on this monitor. */
0104   virtual void notify() const;
0105
0106   /** Wakes up all waiting threads on this monitor. */
0107   virtual void notifyAll() const;
0108
0109 private:
0110   class Impl;
0111
0112   Impl* impl_;
0113 };
0114
0115 class Synchronized {
0116 public:
0117   Synchronized(const Monitor* monitor) : g(monitor->mutex()) {}
0118   Synchronized(const Monitor& monitor) : g(monitor.mutex()) {}
0119
0120 private:
0121   Guard g;
0122 };
0123 }
0124 }
0125 } // apache::thrift::concurrency
0126
0127 #endif // #ifndef _THRIFT_CONCURRENCY_MONITOR_H_