java.hpp (16382B)
1 /* Relacy Race Detector 2 * Copyright (c) 2008-2013, Dmitry S. Vyukov 3 * All rights reserved. 4 * This software is provided AS-IS with no warranty, either express or implied. 5 * This software is distributed under a license and may not be copied, 6 * modified or distributed except as expressly authorized under the 7 * terms of the license contained in the file LICENSE in this distribution. 8 */ 9 10 #ifndef RL_JAVA_HPP 11 #define RL_JAVA_HPP 12 #ifdef _MSC_VER 13 # pragma once 14 #endif 15 16 #include "base.hpp" 17 18 19 namespace rl 20 { 21 22 /* 23 24 Hierarchy For Package java.util.concurrent.locks 25 26 Class Hierarchy 27 28 * java.lang.Object 29 o java.util.concurrent.locks.AbstractQueuedSynchronizer (implements java.io.Serializable) 30 o java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject (implements java.util.concurrent.locks.Condition, java.io.Serializable) 31 o java.util.concurrent.locks.LockSupport 32 o java.util.concurrent.locks.ReentrantLock (implements java.util.concurrent.locks.Lock, java.io.Serializable) 33 o java.util.concurrent.locks.ReentrantReadWriteLock (implements java.util.concurrent.locks.ReadWriteLock, java.io.Serializable) 34 o java.util.concurrent.locks.ReentrantReadWriteLock.ReadLock (implements java.util.concurrent.locks.Lock, java.io.Serializable) 35 o java.util.concurrent.locks.ReentrantReadWriteLock.WriteLock (implements java.util.concurrent.locks.Lock, java.io.Serializable) 36 37 Interface Hierarchy 38 39 * java.util.concurrent.locks.Condition 40 * java.util.concurrent.locks.Lock 41 * java.util.concurrent.locks.ReadWriteLock 42 */ 43 44 45 46 47 48 /* 49 50 java.util.concurrent.Semaphore 51 52 53 54 Public Constructors 55 public Semaphore(int permits) 56 Creates a Semaphore with the given number of permits and nonfair fairness setting. 57 Parameters 58 permits the initial number of permits available. This value may be negative, in which case releases must occur before any acquires will be granted. 59 public Semaphore(int permits, boolean fair) 60 Creates a Semaphore with the given number of permits and the given fairness setting. 61 Parameters 62 permits the initial number of permits available. This value may be negative, in which case releases must occur before any acquires will be granted. 63 fair true if this semaphore will guarantee first-in first-out granting of permits under contention, else false. 64 Public Methods 65 public void acquire() 66 Acquires a permit from this semaphore, blocking until one is available, or the thread is interrupted. 67 68 Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one. 69 70 If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens: 71 72 * Some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit; or 73 * Some other thread interrupts the current thread. 74 75 If the current thread: 76 77 * has its interrupted status set on entry to this method; or 78 * is interrupted while waiting for a permit, 79 80 then InterruptedException is thrown and the current thread's interrupted status is cleared. 81 Throws 82 InterruptedException if the current thread is interrupted 83 See Also 84 85 * interrupt() 86 87 public void acquire(int permits) 88 Acquires the given number of permits from this semaphore, blocking until all are available, or the thread is interrupted. 89 90 Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount. 91 92 If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens: 93 94 * Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request; or 95 * Some other thread interrupts the current thread. 96 97 If the current thread: 98 99 * has its interrupted status set on entry to this method; or 100 * is interrupted while waiting for a permit, 101 102 then InterruptedException is thrown and the current thread's interrupted status is cleared. Any permits that were to be assigned to this thread are instead assigned to the next waiting thread(s), as if they had been made available by a call to release(). 103 Parameters 104 permits the number of permits to acquire 105 Throws 106 InterruptedException if the current thread is interrupted 107 IllegalArgumentException if permits less than zero. 108 See Also 109 110 * interrupt() 111 112 public void acquireUninterruptibly(int permits) 113 Acquires the given number of permits from this semaphore, blocking until all are available. 114 115 Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount. 116 117 If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request. 118 119 If the current thread is interrupted while waiting for permits then it will continue to wait and its position in the queue is not affected. When the thread does return from this method its interrupt status will be set. 120 Parameters 121 permits the number of permits to acquire 122 Throws 123 IllegalArgumentException if permits less than zero. 124 public void acquireUninterruptibly() 125 Acquires a permit from this semaphore, blocking until one is available. 126 127 Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one. 128 129 If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit. 130 131 If the current thread is interrupted while waiting for a permit then it will continue to wait, but the time at which the thread is assigned a permit may change compared to the time it would have received the permit had no interruption occurred. When the thread does return from this method its interrupt status will be set. 132 public int availablePermits() 133 Returns the current number of permits available in this semaphore. 134 135 This method is typically used for debugging and testing purposes. 136 Returns 137 138 * the number of permits available in this semaphore. 139 140 public int drainPermits() 141 Acquire and return all permits that are immediately available. 142 Returns 143 144 * the number of permits 145 146 public final int getQueueLength() 147 Returns an estimate of the number of threads waiting to acquire. The value is only an estimate because the number of threads may change dynamically while this method traverses internal data structures. This method is designed for use in monitoring of the system state, not for synchronization control. 148 Returns 149 150 * the estimated number of threads waiting for this lock 151 152 public final boolean hasQueuedThreads() 153 Queries whether any threads are waiting to acquire. Note that because cancellations may occur at any time, a true return does not guarantee that any other thread will ever acquire. This method is designed primarily for use in monitoring of the system state. 154 Returns 155 156 * true if there may be other threads waiting to acquire the lock. 157 158 public boolean isFair() 159 Returns true if this semaphore has fairness set true. 160 Returns 161 162 * true if this semaphore has fairness set true. 163 164 public void release(int permits) 165 Releases the given number of permits, returning them to the semaphore. 166 167 Releases the given number of permits, increasing the number of available permits by that amount. If any threads are blocking trying to acquire permits, then the one that has been waiting the longest is selected and given the permits that were just released. If the number of available permits satisfies that thread's request then that thread is re-enabled for thread scheduling purposes; otherwise the thread continues to wait. If there are still permits available after the first thread's request has been satisfied, then those permits are assigned to the next waiting thread. If it is satisfied then it is re-enabled for thread scheduling purposes. This continues until there are insufficient permits to satisfy the next waiting thread, or there are no more waiting threads. 168 169 There is no requirement that a thread that releases a permit must have acquired that permit by calling acquire. Correct usage of a semaphore is established by programming convention in the application. 170 Parameters 171 permits the number of permits to release 172 Throws 173 IllegalArgumentException if permits less than zero. 174 public void release() 175 Releases a permit, returning it to the semaphore. 176 177 Releases a permit, increasing the number of available permits by one. If any threads are blocking trying to acquire a permit, then one is selected and given the permit that was just released. That thread is re-enabled for thread scheduling purposes. 178 179 There is no requirement that a thread that releases a permit must have acquired that permit by calling acquire(). Correct usage of a semaphore is established by programming convention in the application. 180 public String toString() 181 Returns a string identifying this semaphore, as well as its state. The state, in brackets, includes the String "Permits =" followed by the number of permits. 182 Returns 183 184 * a string identifying this semaphore, as well as its state 185 186 public boolean tryAcquire(long timeout, TimeUnit unit) 187 Acquires a permit from this semaphore, if one becomes available within the given waiting time and the current thread has not been interrupted. 188 189 Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one. 190 191 If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens: 192 193 * Some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit; or 194 * Some other thread interrupts the current thread; or 195 * The specified waiting time elapses. 196 197 If a permit is acquired then the value true is returned. 198 199 If the current thread: 200 201 * has its interrupted status set on entry to this method; or 202 * is interrupted while waiting to acquire a permit, 203 204 then InterruptedException is thrown and the current thread's interrupted status is cleared. 205 206 If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all. 207 Parameters 208 timeout the maximum time to wait for a permit 209 unit the time unit of the timeout argument. 210 Returns 211 212 * true if a permit was acquired and false if the waiting time elapsed before a permit was acquired. 213 214 Throws 215 InterruptedException if the current thread is interrupted 216 See Also 217 218 * interrupt() 219 220 public boolean tryAcquire(int permits, long timeout, TimeUnit unit) 221 Acquires the given number of permits from this semaphore, if all become available within the given waiting time and the current thread has not been interrupted. 222 223 Acquires the given number of permits, if they are available and returns immediately, with the value true, reducing the number of available permits by the given amount. 224 225 If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens: 226 227 * Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request; or 228 * Some other thread interrupts the current thread; or 229 * The specified waiting time elapses. 230 231 If the permits are acquired then the value true is returned. 232 233 If the current thread: 234 235 * has its interrupted status set on entry to this method; or 236 * is interrupted while waiting to acquire the permits, 237 238 then InterruptedException is thrown and the current thread's interrupted status is cleared. Any permits that were to be assigned to this thread, are instead assigned to the next waiting thread(s), as if they had been made available by a call to release(). 239 240 If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all. Any permits that were to be assigned to this thread, are instead assigned to the next waiting thread(s), as if they had been made available by a call to release(). 241 Parameters 242 permits the number of permits to acquire 243 timeout the maximum time to wait for the permits 244 unit the time unit of the timeout argument. 245 Returns 246 247 * true if all permits were acquired and false if the waiting time elapsed before all permits were acquired. 248 249 Throws 250 InterruptedException if the current thread is interrupted 251 IllegalArgumentException if permits less than zero. 252 See Also 253 254 * interrupt() 255 256 public boolean tryAcquire(int permits) 257 Acquires the given number of permits from this semaphore, only if all are available at the time of invocation. 258 259 Acquires the given number of permits, if they are available, and returns immediately, with the value true, reducing the number of available permits by the given amount. 260 261 If insufficient permits are available then this method will return immediately with the value false and the number of available permits is unchanged. 262 263 Even when this semaphore has been set to use a fair ordering policy, a call to tryAcquire will immediately acquire a permit if one is available, whether or not other threads are currently waiting. This "barging" behavior can be useful in certain circumstances, even though it breaks fairness. If you want to honor the fairness setting, then use tryAcquire(permits, 0, TimeUnit.SECONDS) which is almost equivalent (it also detects interruption). 264 Parameters 265 permits the number of permits to acquire 266 Returns 267 268 * true if the permits were acquired and false otherwise. 269 270 Throws 271 IllegalArgumentException if permits less than zero. 272 public boolean tryAcquire() 273 Acquires a permit from this semaphore, only if one is available at the time of invocation. 274 275 Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one. 276 277 If no permit is available then this method will return immediately with the value false. 278 279 Even when this semaphore has been set to use a fair ordering policy, a call to tryAcquire() will immediately acquire a permit if one is available, whether or not other threads are currently waiting. This "barging" behavior can be useful in certain circumstances, even though it breaks fairness. If you want to honor the fairness setting, then use tryAcquire(0, TimeUnit.SECONDS) which is almost equivalent (it also detects interruption). 280 Returns 281 282 * true if a permit was acquired and false otherwise. 283 284 Protected Methods 285 protected Collection<Thread> getQueuedThreads() 286 Returns a collection containing threads that may be waiting to acquire. Because the actual set of threads may change dynamically while constructing this result, the returned collection is only a best-effort estimate. The elements of the returned collection are in no particular order. This method is designed to facilitate construction of subclasses that provide more extensive monitoring facilities. 287 Returns 288 289 * the collection of threads 290 291 protected void reducePermits(int reduction) 292 Shrinks the number of available permits by the indicated reduction. This method can be useful in subclasses that use semaphores to track resources that become unavailable. This method differs from acquire in that it does not block waiting for permits to become available. 293 Parameters 294 reduction the number of permits to remove 295 Throws 296 IllegalArgumentException if reduction is negative 297 */ 298 299 } 300 301 #endif