activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tab...@apache.org
Subject svn commit: r818116 - in /activemq/activemq-cpp/trunk/activemq-cpp/src/main/decaf/util/concurrent/locks: Lock.h ReentrantLock.h
Date Wed, 23 Sep 2009 14:27:38 GMT
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;
+
     };
 
 }}}}



Mime
View raw message