Author: tabish
Date: Wed Sep 23 14:27:37 2009
New Revision: 818116
URL: http://svn.apache.org/viewvc?rev=818116&view=rev
Log:
Further refine the Locks package API.
Modified:
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/Lock.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/ReentrantLock.h
Modified:
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/Lock.h
URL:
http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/Lock.h?rev=818116&r1=818115&r2=818116&view=diff
==============================================================================
---
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/Lock.h
(original)
+++
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/Lock.h
Wed Sep 23 14:27:37 2009
@@ -259,8 +259,10 @@
* type must be documented by that Lock implementation.
*
* @throws RuntimeException if an error occurs while acquiring the
lock.
+ * @throws IllegalMonitorStateException if the current thread is not
the owner of the lock.
*/
- virtual void unlock() throw( decaf::lang::exceptions::RuntimeException
) = 0;
+ virtual void unlock() throw( decaf::lang::exceptions::RuntimeException,
+
decaf::lang::exceptions::IllegalMonitorStateException ) = 0;
/**
* Returns a new Condition instance that is bound to this Lock
instance.
Modified:
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/ReentrantLock.h
URL:
http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/ReentrantLock.h?rev=818116&r1=818115&r2=818116&view=diff
==============================================================================
---
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/ReentrantLock.h
(original)
+++
activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks/ReentrantLock.h
Wed Sep 23 14:27:37 2009
@@ -76,9 +76,6 @@
* getLockQueueLength, as well as some associated protected access methods
that may be useful
* for instrumentation and monitoring.
*
- * This lock supports a maximum of 2147483647 recursive locks by the same
thread. Attempts
- * to exceed this limit result in Error throws from locking methods.
- *
* @since 1.0
*/
class DECAF_API ReentrantLock : public Lock {
@@ -92,6 +89,273 @@
virtual ~ReentrantLock();
+ /**
+ * Acquires the lock.
+ *
+ * Acquires the lock if it is not held by another thread and returns
immediately, setting
+ * the lock hold count to one.
+ *
+ * If the current thread already holds the lock then the hold count is
incremented by one
+ * and the method returns immediately.
+ *
+ * If the lock is held by another thread then the current thread
becomes disabled for thread
+ * scheduling purposes and lies dormant until the lock has been
acquired, at which time the
+ * lock hold count is set to one.
+ *
+ * @throws RuntimeException if an error occurs while acquiring the
lock.
+ */
+ virtual void lock() throw( decaf::lang::exceptions::RuntimeException );
+
+ /**
+ * Acquires the lock unless the current thread is interrupted.
+ *
+ * Acquires the lock if it is not held by another thread and returns
immediately, setting
+ * the lock hold count to one.
+ *
+ * If the current thread already holds this lock then the hold count
is incremented by one and
+ * the method returns immediately.
+ *
+ * If the lock is held by another thread then the current thread
becomes disabled for thread
+ * scheduling purposes and lies dormant until one of two things
happens:
+ *
+ * * The lock is acquired by the current thread; or
+ * * Some other thread interrupts the current thread.
+ *
+ * If the lock is acquired by the current thread then the lock hold
count is set to one.
+ *
+ * If the current thread:
+ *
+ * * has its interrupted status set on entry to this method; or
+ * * is interrupted while acquiring the lock,
+ *
+ * then InterruptedException is thrown and the current thread's
interrupted status is cleared.
+ *
+ * In this implementation, as this method is an explicit interruption
point, preference is given
+ * to responding to the interrupt over normal or reentrant acquisition
of the lock.
+ *
+ * @throws RuntimeException if an error occurs while acquiring the
lock.
+ * @throws InterruptedException
+ * if the current thread is interrupted while acquiring the
lock (and
+ * interruption of lock acquisition is supported).
+ */
+ virtual void lockInterruptibly() throw (
decaf::lang::exceptions::RuntimeException,
+
decaf::lang::exceptions::InterruptedException );
+
+ /**
+ * Acquires the lock only if it is not held by another thread at the
time of invocation.
+ *
+ * Acquires the lock if it is not held by another thread and returns
immediately with the
+ * value true, setting the lock hold count to one. Even when this lock
has been set to use
+ * a fair ordering policy, a call to tryLock() will immediately
acquire the lock if it is
+ * available, whether or not other threads are currently waiting for
the lock. This
+ * "barging" behavior can be useful in certain circumstances, even
though it breaks fairness.
+ * If you want to honor the fairness setting for this lock, then use
tryLock(0, TimeUnit.SECONDS)
+ * which is almost equivalent (it also detects interruption).
+ *
+ * If the current thread already holds this lock then the hold count
is incremented by one
+ * and the method returns true.
+ *
+ * If the lock is held by another thread then this method will return
immediately with the
+ * value false.
+ *
+ * @returns true if the lock was acquired and false otherwise
+ *
+ * @throws RuntimeException if an error occurs while acquiring the
lock.
+ */
+ virtual bool tryLock() throw(
decaf::lang::exceptions::RuntimeException );
+
+ /**
+ * Acquires the lock if it is not held by another thread within the
given waiting time and the
+ * current thread has not been interrupted.
+ *
+ * Acquires the lock if it is not held by another thread and returns
immediately with the value
+ * true, setting the lock hold count to one. If this lock has been set
to use a fair ordering
+ * policy then an available lock will not be acquired if any other
threads are waiting for the
+ * lock. This is in contrast to the tryLock() method. If you want a
timed tryLock that does
+ * permit barging on a fair lock then combine the timed and un-timed
forms together:
+ *
+ * if (lock.tryLock() || lock.tryLock(timeout, unit) ) { ... }
+ *
+ * If the current thread already holds this lock then the hold count
is incremented by one and
+ * the method returns true.
+ *
+ * If the lock is held by another thread then the current thread
becomes disabled for thread
+ * scheduling purposes and lies dormant until one of three things
happens:
+ *
+ * * The lock is acquired by the current thread; or
+ * * Some other thread interrupts the current thread; or
+ * * The specified waiting time elapses
+ *
+ * If the lock is acquired then the value true is returned and the
lock hold count is set to one.
+ *
+ * If the current thread:
+ *
+ * * has its interrupted status set on entry to this method; or
+ * * is interrupted while acquiring the lock,
+ *
+ * then InterruptedException is thrown and the current thread's
interrupted status is cleared.
+ *
+ * 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.
+ *
+ * In this implementation, as this method is an explicit interruption
point, preference is given
+ * to responding to the interrupt over normal or reentrant acquisition
of the lock, and over
+ * reporting the elapse of the waiting time.
+ *
+ * @param time
+ * the maximum time to wait for the lock
+ * @param unit
+ * the time unit of the time argument
+ *
+ * @returns true if the lock was acquired and false if the waiting
time elapsed
+ * before the lock was acquired
+ *
+ * @throws RuntimeException if an error occurs while acquiring the
lock.
+ * @throws InterruptedException
+ * if the current thread is interrupted while acquiring the
lock (and
+ * interruption of lock acquisition is supported)
+ */
+ virtual bool tryLock( long long time, const TimeUnit& unit )
+ throw ( decaf::lang::exceptions::RuntimeException,
+ decaf::lang::exceptions::InterruptedException );
+
+ /**
+ * Attempts to release this lock.
+ *
+ * If the current thread is the holder of this lock then the hold
count is decremented.
+ * If the hold count is now zero then the lock is released. If the
current thread is not
+ * the holder of this lock then IllegalMonitorStateException is thrown.
+ *
+ * @throws RuntimeException if an error occurs while acquiring the
lock.
+ */
+ virtual void unlock() throw( decaf::lang::exceptions::RuntimeException,
+
decaf::lang::exceptions::IllegalMonitorStateException );
+
+ /**
+ * Returns a Condition instance for use with this Lock instance.
+ *
+ * The returned Condition instance supports the same usages as do the
Mutex Class' methods
+ * (wait, notify, and notifyAll).
+ *
+ * * If this lock is not held when any of the Condition waiting or
signalling methods are
+ * called, then an IllegalMonitorStateException is thrown.
+ * * When the condition waiting methods are called the lock is
released and, before they
+ * return, the lock is reacquired and the lock hold count restored
to what it was when
+ * the method was called.
+ * * If a thread is interrupted while waiting then the wait will
terminate, an
+ * InterruptedException will be thrown, and the thread's
interrupted status will be cleared.
+ * * Waiting threads are signaled in FIFO order.
+ * * The ordering of lock reacquisition for threads returning from
waiting methods is the
+ * same as for threads initially acquiring the lock, which is in
the default case not
+ * specified, but for fair locks favors those threads that have
been waiting the longest.
+ *
+ * @throws RuntimeException if an error occurs while creating the
Condition.
+ * @throws UnsupportedOperationException
+ * if this Lock implementation does not support conditions
+ */
+ virtual Condition* newCondition()
+ throw ( decaf::lang::exceptions::RuntimeException,
+ decaf::lang::exceptions::UnsupportedOperationException );
+
+ /**
+ * Queries the number of holds on this lock by the current thread.
+ *
+ * A thread has a hold on a lock for each lock action that is not
matched by an unlock action.
+ *
+ * The hold count information is typically only used for testing and
debugging purposes. For
+ * example, if a certain section of code should not be entered with
the lock already held
+ * then we can assert that fact:
+ *
+ * class X {
+ * private:
+ *
+ * ReentrantLock lock;
+ * // ...
+ *
+ * public:
+ *
+ * void m() {
+ * assert( lock.getHoldCount() == 0 );
+ * lock.lock();
+ * try {
+ * // ... method body
+ * } catch(...) {
+ * lock.unlock();
+ * }
+ * }
+ * }
+ *
+ * @returns the number of holds on this lock by the current thread, or
zero if this lock
+ * is not held by the current thread
+ */
+ int getHoldCount() const;
+
+ /**
+ * Queries if this lock is held by the current thread.
+ *
+ * This method is typically used for debugging and testing. For
example, a method that
+ * should only be called while a lock is held can assert that this is
the case:
+ *
+ * class X {
+ * private:
+ * ReentrantLock lock = new ReentrantLock();
+ * // ...
+ *
+ * public:
+ * void m() {
+ * assert( lock.isHeldByCurrentThread() );
+ * // ... method body
+ * }
+ * }
+ *
+ * It can also be used to ensure that a reentrant lock is used in a
non-reentrant
+ * manner, for example:
+ *
+ * class X {
+ * private:
+ * ReentrantLock lock = new ReentrantLock();
+ * // ...
+ *
+ * public:
+ * void m() {
+ * assert !lock.isHeldByCurrentThread();
+ * lock.lock();
+ * try {
+ * // ... method body
+ * } finally {
+ * lock.unlock();
+ * }
+ * }
+ * }
+ *
+ * @returns true if current thread holds this lock and false otherwise
+ */
+ bool isHeldByCurrentThread() const;
+
+ /**
+ * Queries if this lock is held by any thread. This method is designed
for use in
+ * monitoring of the system state, not for synchronization control.
+ *
+ * @returns true if any thread holds this lock and false otherwise
+ */
+ bool isLocked() const;
+
+ /**
+ * Returns true if this lock has fairness set true.
+ *
+ * @returns true if this lock has fairness set true
+ */
+ bool isFair() const;
+
+ /**
+ * Returns a string identifying this lock, as well as its lock state.
The state, in
+ * brackets, includes either the String "Unlocked" or the String
"Locked by" followed
+ * by the name of the owning thread.
+ *
+ * @returns a string identifying this lock, as well as its lock state
+ */
+ std::string toString() const;
+
};
}}}}
