activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tab...@apache.org
Subject svn commit: r712296 - in /activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent: Delayed.h locks/ locks/Condition.h locks/Lock.h locks/ReadWriteLock.h
Date Fri, 07 Nov 2008 22:41:03 GMT
Author: tabish
Date: Fri Nov  7 14:41:02 2008
New Revision: 712296

URL: http://svn.apache.org/viewvc?rev=712296&view=rev
Log:
Add some additional interfaces to Decaf

Added:
    activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/Delayed.h
    activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/
    activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Condition.h
    activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Lock.h
    activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/ReadWriteLock.h

Added: activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/Delayed.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/Delayed.h?rev=712296&view=auto
==============================================================================
--- activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/Delayed.h (added)
+++ activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/Delayed.h Fri Nov  7 14:41:02
2008
@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _DECAF_UTIL_CONCURRENT_DELAYED_H_
+#define _DECAF_UTIL_CONCURRENT_DELAYED_H_
+
+#include <decaf/util/Config.h>
+
+#include <decaf/lang/Comparable.h>
+#include <decaf/util/concurrent/TimeUnit.h>
+
+namespace decaf {
+namespace util {
+namespace concurrent {
+
+    /**
+     * A mix-in style interface for marking objects that should be acted upon after a
+     * given delay.
+     * <p>
+     * An implementation of this interface must define a Comparable methods that provides
an
+     * ordering consistent with its getDelay method.
+     */
+    class DECAF_API Delayed : public decaf::lang::Comparable<Delayed> {
+    public:
+
+        virtual ~Delayed() {}
+
+        /**
+         * Returns the remaining delay associated with this object, in the given time unit.
+         *
+         * @param unit
+         *        The time unit
+         *
+         * @returns the remaining delay; zero or negative values indicate that the delay
+         *          has already elapsed
+         */
+        virtual long long getDelay( const TimeUnit& unit ) = 0;
+
+    };
+
+}}}
+
+#endif /* _DECAF_UTIL_CONCURRENT_DELAYED_H_ */

Added: activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Condition.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Condition.h?rev=712296&view=auto
==============================================================================
--- activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Condition.h (added)
+++ activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Condition.h Fri Nov 
7 14:41:02 2008
@@ -0,0 +1,411 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _DECAF_UTIL_CONCURRENT_LOCKS_CONDITION_H_
+#define _DECAF_UTIL_CONCURRENT_LOCKS_CONDITION_H_
+
+#include <decaf/util/Config.h>
+
+#include <decaf/lang/exceptions/InterruptedException.h>
+#include <decaf/lang/exceptions/IllegalMonitorStateException.h>
+
+namespace decaf {
+namespace util {
+namespace concurrent {
+namespace locks {
+
+    /**
+     * Condition factors out the Mutex monitor methods (wait, notify  and notifyAll) into
+     * distinct objects to give the effect of having multiple wait-sets per object, by
+     * combining them with the use of arbitrary Lock implementations. Where a Lock replaces
+     * the use of synchronized statements, a Condition replaces the use of the Object monitor
+     * methods.
+     *
+     * Conditions (also known as condition queues or condition variables) provide a means
for
+     * one thread to suspend execution (to "wait") until notified by another thread that
some
+     * state condition may now be true. Because access to this shared state information occurs
+     * in different threads, it must be protected, so a lock of some form is associated with
+     * the condition. The key property that waiting for a condition provides is that it
+     * atomically releases the associated lock and suspends the current thread.
+     *
+     * A Condition instance is intrinsically bound to a lock. To obtain a Condition instance
+     * for a particular Lock instance use its newCondition() method.
+     *
+     * As an example, suppose we have a bounded buffer which supports put and take methods.
+     * If a take is attempted on an empty buffer, then the thread will block until an item
+     * becomes available; if a put is attempted on a full buffer, then the thread will block
+     * until a space becomes available. We would like to keep waiting put threads and take
+     * threads in separate wait-sets so that we can use the optimization of only notifying
a
+     * single thread at a time when items or spaces become available in the buffer. This
can
+     * be achieved using two Condition instances.
+     *
+     *   class BoundedBuffer {
+     *      Lock* lock = new ReentrantLock();
+     *      Condition* notFull  = lock->newCondition();
+     *      Condition* notEmpty = lock->newCondition();
+     *
+     *      Object* items = new Object[100];
+     *      int putptr, takeptr, count;
+     *
+     *      public void put( Object* x ) throw( InterruptedException ) {
+     *        lock->lock();
+     *        try {
+     *          while( count == 100 )
+     *            notFull->await();
+     *          items[putptr] = x;
+     *          if (++putptr == 100) putptr = 0;
+     *          ++count;
+     *          notEmpty->signal();
+     *        } catch(...) {
+     *          lock->unlock();
+     *        }
+     *      }
+     *
+     *      public Object take() throw( InterruptedException ) {
+     *        lock->lock();
+     *        try {
+     *          while(count == 0)
+     *            notEmpty->await();
+     *          Object x = items[takeptr];
+     *          if (++takeptr == 100) takeptr = 0;
+     *          --count;
+     *          notFull->signal();
+     *          return x;
+     *        } catch(...) {
+     *          lock->unlock();
+     *        }
+     *      }
+     *    }
+     *
+     * (The ArrayBlockingQueue class provides this functionality, so there is no reason to
+     * implement this sample usage class.)
+     *
+     * Implementation Considerations
+     *
+     * When waiting upon a Condition, a "spurious wakeup" is permitted to occur, in general,
+     * as a concession to the underlying platform semantics. This has little practical impact
+     * on most application programs as a Condition should always be waited upon in a loop,
+     * testing the state predicate that is being waited for. An implementation is free to
+     * remove the possibility of spurious wakeups but it is recommended that applications
+     * programmers always assume that they can occur and so always wait in a loop.
+     *
+     * The three forms of condition waiting (interruptible, non-interruptible, and timed)
+     * may differ in their ease of implementation on some platforms and in their performance
+     * characteristics. In particular, it may be difficult to provide these features and
+     * maintain specific semantics such as ordering guarantees. Further, the ability to
+     * interrupt the actual suspension of the thread may not always be feasible to
+     * implement on all platforms.
+     *
+     * Consequently, an implementation is not required to define exactly the same guarantees
+     * or semantics for all three forms of waiting, nor is it required to support interruption
+     * of the actual suspension of the thread.
+     *
+     * An implementation is required to clearly document the semantics and guarantees provided
+     * by each of the waiting methods, and when an implementation does support interruption
+     * of thread suspension then it must obey the interruption semantics as defined in this
+     * interface.
+     *
+     * As interruption generally implies cancellation, and checks for interruption are often
+     * infrequent, an implementation can favor responding to an interrupt over normal method
+     * return. This is true even if it can be shown that the interrupt occurred after another
+     * action may have unblocked the thread. An implementation should document this behavior.
+     *
+     * @since 1.0
+     */
+    class DECAF_API Condition {
+    public:
+
+        virtual ~Condition() {}
+
+        /**
+         * Causes the current thread to wait until it is signalled or interrupted.
+         * <p>
+         * The lock associated with this Condition is atomically released and the current
+         * thread becomes disabled for thread scheduling purposes and lies dormant until
one
+         * of four things happens:
+         *
+         *   * Some other thread invokes the signal() method for this Condition and the
+         *     current thread happens to be chosen as the thread to be awakened; or
+         *   * Some other thread invokes the signalAll() method for this Condition; or
+         *   * Some other thread interrupts the current thread, and interruption of thread
+         *     suspension is supported; or
+         *   * A "spurious wakeup" occurs.
+         *
+         * In all cases, before this method can return the current thread must re-acquire
the
+         * lock associated with this condition. When the thread returns it is guaranteed
to
+         * hold this lock.
+         *
+         * If the current thread:
+         *
+         *   * has its interrupted status set on entry to this method; or
+         *   * is interrupted while waiting and interruption of thread suspension is supported,
+         *
+         * then InterruptedException is thrown and the current thread's interrupted status
is
+         * cleared. It is not specified, in the first case, whether or not the test for
+         * interruption occurs before the lock is released.
+         *
+         * Implementation Considerations
+         *
+         * The current thread is assumed to hold the lock associated with this Condition
when
+         * this method is called. It is up to the implementation to determine if this is
the
+         * case and if not, how to respond. Typically, an exception will be thrown (such
as
+         * IllegalMonitorStateException) and the implementation must document that fact.
+         *
+         * An implementation can favor responding to an interrupt over normal method return
+         * in response to a signal. In that case the implementation must ensure that the
+         * signal is redirected to another waiting thread, if there is one.
+         *
+         * @throws InterruptedException
+         *         if the current thread is interrupted (and interruption of thread
+         *         suspension is supported)
+         *
+         * @throws IllegalMonitorStateException
+         *         if the caller is not the lock owner.
+         */
+        virtual void await()
+            throw( decaf::lang::exceptions::InterruptedException,
+                   decaf::lang::exceptions::IllegalMonitorStateException ) = 0;
+
+        /**
+         * Causes the current thread to wait until it is signalled.
+         * <p>
+         * The lock associated with this condition is atomically released and the current
+         * thread becomes disabled for thread scheduling purposes and lies dormant until
+         * one of three things happens:
+         *
+         *   * Some other thread invokes the signal() method for this Condition and the
+         *     current thread happens to be chosen as the thread to be awakened; or
+         *   * Some other thread invokes the signalAll() method for this Condition; or
+         *   * A "spurious wakeup" occurs.
+         *
+         * In all cases, before this method can return the current thread must re-acquire
+         * the lock associated with this condition. When the thread returns it is guaranteed
+         * to hold this lock.
+         *
+         * If the current thread's interrupted status is set when it enters this method,
or
+         * it is interrupted while waiting, it will continue to wait until signalled. When
+         * it finally returns from this method its interrupted status will still be set.
+         *
+         * Implementation Considerations
+         *
+         * The current thread is assumed to hold the lock associated with this Condition
+         * when this method is called. It is up to the implementation to determine if this
+         * is the case and if not, how to respond. Typically, an exception will be thrown
+         * (such as IllegalMonitorStateException) and the implementation must document
+         * that fact.
+         *
+         * @throws IllegalMonitorStateException
+         *         if the caller is not the lock owner.
+         */
+        virtual void awaitUninterruptibly()
+            throw( decaf::lang::exceptions::IllegalMonitorStateException ) = 0;
+
+        /**
+         * Causes the current thread to wait until it is signalled or interrupted, or
+         * the specified waiting time elapses.
+         * <p>
+         * The lock associated with this condition is atomically released and the current
+         * thread becomes disabled for thread scheduling purposes and lies dormant until
+         * one of five things happens:
+         *
+         *   * Some other thread invokes the signal() method for this Condition and the
+         *     current thread happens to be chosen as the thread to be awakened; or
+         *   * Some other thread invokes the signalAll() method for this Condition; or
+         *   * Some other thread interrupts the current thread, and interruption of thread
+         *     suspension is supported; or
+         *   * The specified waiting time elapses; or
+         *   * A "spurious wakeup" occurs.
+         *
+         * In all cases, before this method can return the current thread must re-acquire
+         * the lock associated with this condition. When the thread returns it is guaranteed
+         * to hold this lock.
+         *
+         * If the current thread:
+         *
+         *   * has its interrupted status set on entry to this method; or
+         *   * is interrupted while waiting and interruption of thread suspension is supported,
+         *
+         * then InterruptedException is thrown and the current thread's interrupted status
is
+         * cleared. It is not specified, in the first case, whether or not the test for
+         * interruption occurs before the lock is released.
+         *
+         * The method returns an estimate of the number of nanoseconds remaining to wait
given
+         * the supplied nanosTimeout value upon return, or a value less than or equal to
zero
+         * if it timed out. This value can be used to determine whether and how long to re-wait
+         * in cases where the wait returns but an awaited condition still does not hold.
+         * Typical uses of this method take the following form:
+         *
+         *    synchronized boolean aMethod( long timeout, const TimeUnit& unit ) {
+         *      long nanosTimeout = unit.toNanos(timeout);
+         *      while (!conditionBeingWaitedFor) {
+         *        if (nanosTimeout > 0)
+         *            nanosTimeout = theCondition->awaitNanos(nanosTimeout);
+         *        else
+         *           return false;
+         *      }
+         *      // ...
+         *    }
+         *
+         * Design note: This method requires a nanosecond argument so as to avoid truncation
+         * errors in reporting remaining times. Such precision loss would make it difficult
+         * for programmers to ensure that total waiting times are not systematically shorter
+         * than specified when re-waits occur.
+         *
+         * Implementation Considerations
+         *
+         * The current thread is assumed to hold the lock associated with this Condition
when
+         * this method is called. It is up to the implementation to determine if this is
the
+         * case and if not, how to respond. Typically, an exception will be thrown (such
as
+         * IllegalMonitorStateException) and the implementation must document that fact.
+         *
+         * An implementation can favor responding to an interrupt over normal method return
in
+         * response to a signal, or over indicating the elapse of the specified waiting time.
+         * In either case the implementation must ensure that the signal is redirected to
+         * another waiting thread, if there is one.
+         *
+         * @param nanosTimeout - the maximum time to wait, in nanoseconds
+         *
+         * @returns an estimate of the nanosTimeout value minus the time spent waiting upon
+         *          return from this method. A positive value may be used as the argument
to
+         *          a subsequent call to this method to finish waiting out the desired time.
+         *          A value less than or equal to zero indicates that no time remains.
+         *
+         * @throws InterruptedException
+         *         if the current thread is interrupted (and interruption of thread suspension
+         *         is supported)
+         *
+         * @throws IllegalMonitorStateException
+         *         if the caller is not the lock owner.
+         */
+        virtual long long awaitNanos( long long nanosTimeout )
+            throw( decaf::lang::exceptions::InterruptedException,
+                   decaf::lang::exceptions::IllegalMonitorStateException ) = 0;
+
+        /**
+         * Causes the current thread to wait until it is signalled or interrupted, or the
+         * specified waiting time elapses. This method is behaviorally equivalent to:
+         *
+         *      awaitNanos(unit.toNanos(time)) > 0
+         *
+         * @param time - the maximum time to wait
+         * @param unit - the time unit of the time argument
+         *
+         * @returns false if the waiting time detectably elapsed before return from the
+         *          method, else true
+         *
+         * @throws InterruptedException
+         *         if the current thread is interrupted (and interruption of thread suspension
+         *         is supported)
+         *
+         * @throws IllegalMonitorStateException
+         *         if the caller is not the lock owner.
+         */
+        virtual bool await( long long time, const TimeUnit& unit )
+            throw( decaf::lang::exceptions::InterruptedException,
+                   decaf::lang::exceptions::IllegalMonitorStateException ) = 0;
+
+        /**
+         * Causes the current thread to wait until it is signalled or interrupted, or the
+         * specified deadline elapses.
+         * <p>
+         * The lock associated with this condition is atomically released and the current
+         * thread becomes disabled for thread scheduling purposes and lies dormant until
one
+         * of five things happens:
+         *
+         *   * Some other thread invokes the signal() method for this Condition and the
+         *     current thread happens to be chosen as the thread to be awakened; or
+         *   * Some other thread invokes the signalAll() method for this Condition; or
+         *   * Some other thread interrupts the current thread, and interruption of thread
+         *     suspension is supported; or
+         *   * The specified deadline elapses; or
+         *   * A "spurious wakeup" occurs.
+         *
+         * In all cases, before this method can return the current thread must re-acquire
the
+         * lock associated with this condition. When the thread returns it is guaranteed
to
+         * hold this lock.
+         *
+         * If the current thread:
+         *
+         *   * has its interrupted status set on entry to this method; or
+         *   * is interrupted while waiting and interruption of thread suspension is supported,
+         *
+         * then InterruptedException is thrown and the current thread's interrupted status
is
+         * cleared. It is not specified, in the first case, whether or not the test for
+         * interruption occurs before the lock is released.
+         *
+         * The return value indicates whether the deadline has elapsed, which can be used
as
+         * follows:
+         *
+         *   bool aMethod( const Date& deadline ) {
+         *      bool stillWaiting = true;
+         *      while (!conditionBeingWaitedFor) {
+         *        if (stillWaiting)
+         *            stillWaiting = theCondition->awaitUntil(deadline);
+         *         else
+         *           return false;
+         *      }
+         *      // ...
+         *   }
+         *
+         * Implementation Considerations
+         *
+         * The current thread is assumed to hold the lock associated with this Condition
when
+         * this method is called. It is up to the implementation to determine if this is
the
+         * case and if not, how to respond. Typically, an exception will be thrown (such
as
+         * IllegalMonitorStateException) and the implementation must document that fact.
+         *
+         * An implementation can favor responding to an interrupt over normal method return
+         * in response to a signal, or over indicating the passing of the specified deadline.
+         * In either case the implementation must ensure that the signal is redirected to
+         * another waiting thread, if there is one.
+         *
+         * @param deadline - the absolute time to wait until
+         *
+         * @returns false if the deadline has elapsed upon return, else true
+         *
+         * @throws InterruptedException
+         *         if the current thread is interrupted (and interruption of thread suspension
+         *         is supported)
+         *
+         * @throws IllegalMonitorStateException
+         *         if the caller is not the lock owner.
+         */
+//        virtual bool awaitUntil( Date deadline )
+//            throw( decaf::lang::exceptions::InterruptedException,
+//                   decaf::lang::exceptions::IllegalMonitorStateException ) = 0;
+
+        /**
+         * Wakes up one waiting thread.
+         * <p>
+         * If any threads are waiting on this condition then one is selected for waking up.
+         * That thread must then re-acquire the lock before returning from await.
+         */
+        virtual void signal() = 0;
+
+        /**
+         * Wakes up all waiting threads.
+         * <p>
+         * If any threads are waiting on this condition then they are all woken up. Each
+         * thread must re-acquire the lock before it can return from await.
+         */
+        virtual void signalAll() = 0;
+
+    };
+
+}}}}
+
+#endif /*_DECAF_UTIL_CONCURRENT_LOCKS_CONDITION_H_*/

Added: activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Lock.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Lock.h?rev=712296&view=auto
==============================================================================
--- activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Lock.h (added)
+++ activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/Lock.h Fri Nov  7 14:41:02
2008
@@ -0,0 +1,281 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _DECAF_UTIL_CONCURRENT_LOCKS_LOCK_H_
+#define _DECAF_UTIL_CONCURRENT_LOCKS_LOCK_H_
+
+#include <decaf/util/Config.h>
+
+#include <decaf/lang/exceptions/InterruptedException.h>
+#include <decaf/lang/exceptions/UnsupportedOperationException.h>
+#include <decaf/util/concurrent/locks/Condition.h>
+
+namespace decaf {
+namespace util {
+namespace concurrent {
+namespace locks {
+
+    /**
+     * Lock implementations provide more extensive locking operations than can be
+     * obtained using synchronized statements. They allow more flexible structuring,
+     * may have quite different properties, and may support multiple associated
+     * Condition objects.
+     *
+     * A lock is a tool for controlling access to a shared resource by multiple
+     * threads. Commonly, a lock provides exclusive access to a shared resource:
+     * only one thread at a time can acquire the lock and all access to the shared
+     * resource requires that the lock be acquired first. However, some locks may
+     * allow concurrent access to a shared resource, such as the read lock of a
+     * ReadWriteLock.
+     *
+     * While the scoping mechanism for synchronized statements makes it much easier
+     * easier to program with monitor locks, and helps avoid many common programming
+     * errors involving locks, there are occasions where you need to work with locks
+     * in a more flexible way. For example, some algorithms for traversing concurrently
+     * accessed data structures require the use of "hand-over-hand" or
+     * "chain locking": you acquire the lock of node A, then node B, then release A
+     * and acquire C, then release B and acquire D and so on. Implementations of the
+     * Lock interface enable the use of such techniques by allowing a lock to be
+     * acquired and released in different scopes, and allowing multiple locks to be
+     * acquired and released in any order.
+     *
+     * With this increased flexibility comes additional responsibility. The absence of
+     * block-structured locking removes the automatic release of locks that occurs with
+     * synchronized statements. In most cases, the following idiom should be used:
+     *
+     *    Lock l = ...;
+     *    l.lock();
+     *    try {
+     *        // access the resource protected by this lock
+     *    } catch(...) {
+     *        l.unlock();
+     *    }
+     *
+     * When locking and unlocking occur in different scopes, care must be taken to ensure
+     * that all code that is executed while the lock is held is protected by try-catch
+     * ensure that the lock is released when necessary.
+     *
+     * Lock implementations provide additional functionality over the use of synchronized
+     * methods and statements by providing a non-blocking attempt to acquire a lock
+     * (tryLock()), an attempt to acquire the lock that can be interrupted (lockInterruptibly(),
+     * and an attempt to acquire the lock that can timeout (tryLock(long, TimeUnit)).
+     *
+     * Note that Lock instances are just normal objects and can themselves be used as the
+     * target in a synchronized statement.
+     *
+     * The three forms of lock acquisition (interruptible, non-interruptible, and timed)
+     * may differ in their performance characteristics, ordering guarantees, or other
+     * implementation qualities. Further, the ability to interrupt the ongoing acquisition
+     * of a lock may not be available in a given Lock class. Consequently, an implementation
+     * is not required to define exactly the same guarantees or semantics for all three forms
+     * of lock acquisition, nor is it required to support interruption of an ongoing lock
+     * acquisition. An implementation is required to clearly document the semantics and
+     * guarantees provided by each of the locking methods. It must also obey the interruption
+     * semantics as defined in this interface, to the extent that interruption of lock
+     * acquisition is supported: which is either totally, or only on method entry.
+     *
+     * As interruption generally implies cancellation, and checks for interruption are
+     * often infrequent, an implementation can favor responding to an interrupt over normal
+     * method return. This is true even if it can be shown that the interrupt occurred after
+     * another action may have unblocked the thread. An implementation should document this
+     * behavior.
+     *
+     * @since 1.0
+     */
+    class DECAF_API Lock {
+    public:
+
+        virtual ~Lock() {}
+
+        /**
+         * Acquires the lock.
+         * <p>
+         * If the lock is not available then the current thread becomes disabled for thread
+         * scheduling purposes and lies dormant until the lock has been acquired.
+         * <p>
+         * Implementation Considerations
+         * <p>
+         * A Lock implementation may be able to detect erroneous use of the lock, such as
an
+         * invocation that would cause deadlock, and may throw an (unchecked) exception in
+         * such circumstances. The circumstances and the exception type must be documented
+         * by that Lock implementation.
+         */
+        virtual void lock() = 0;
+
+        /**
+         * Acquires the lock unless the current thread is interrupted.
+         * <p>
+         * Acquires the lock if it is available and returns immediately.
+         * <p>
+         * If the lock is not available 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, and interruption of lock
+         *    acquisition is supported.
+         *
+         * If the current thread:
+         *
+         *  * has its interrupted status set on entry to this method; or
+         *  * is interrupted while acquiring the lock, and interruption of lock acquisition
+         *    is supported,
+         *
+         * then InterruptedException is thrown and the current thread's interrupted status
+         * is cleared.
+         *
+         * Implementation Considerations
+         *
+         * The ability to interrupt a lock acquisition in some implementations may not be
+         * possible, and if possible may be an expensive operation. The programmer should
+         * be aware that this may be the case. An implementation should document when this
+         * is the case.
+         *
+         * An implementation can favor responding to an interrupt over normal method return.
+         *
+         * A Lock implementation may be able to detect erroneous use of the lock, such as
an
+         * invocation that would cause deadlock, and may throw an (unchecked) exception in
+         * such circumstances. The circumstances and the exception type must be documented
+         * by that Lock implementation.
+         *
+         * @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::InterruptedException
) = 0;
+
+        /**
+         * Acquires the lock only if it is free at the time of invocation.
+         * <p>
+         * Acquires the lock if it is available and returns immediately with the value true.
+         * If the lock is not available then this method will return immediately with the
+         * value false.
+         * <p>
+         * A typical usage idiom for this method would be:
+         *
+         *   Lock lock = ...;
+         *   if (lock.tryLock()) {
+         *       try {
+         *            // manipulate protected state
+         *       } catch(...) {
+         *            lock.unlock();
+         *       }
+         *   } else {
+         *       // perform alternative actions
+         *   }
+         *
+         * This usage ensures that the lock is unlocked if it was acquired, and doesn't
+         * try to unlock if the lock was not acquired.
+         *
+         * @returns true if the lock was acquired and false otherwise
+         */
+        virtual bool tryLock() = 0;
+
+        /**
+         * Acquires the lock if it is free within the given waiting time and the current
+         * thread has not been interrupted.
+         * <p>
+         * If the lock is available this method returns immediately with the value true.
+         * If the lock is not available 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, and interruption of lock
+         *     acquisition is supported; or
+         *   * The specified waiting time elapses
+         *
+         * If the lock is acquired then the value true is returned.
+         *
+         * If the current thread:
+         *
+         *   * has its interrupted status set on entry to this method; or
+         *   * is interrupted while acquiring the lock, and interruption of lock acquisition
+         *     is supported,
+         *
+         * 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.
+         *
+         * Implementation Considerations
+         *
+         * The ability to interrupt a lock acquisition in some implementations may not
+         * be possible, and if possible may be an expensive operation. The programmer should
+         * be aware that this may be the case. An implementation should document when this
+         * is the case.
+         *
+         * An implementation can favor responding to an interrupt over normal method return,
+         * or reporting a timeout.
+         *
+         * A Lock implementation may be able to detect erroneous use of the lock, such as
an
+         * invocation that would cause deadlock, and may throw an (unchecked) exception in
+         * such circumstances. The circumstances and the exception type must be documented
by
+         * that Lock implementation.
+         *
+         * @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 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::InterruptedException ) = 0;
+
+        /**
+         * Releases the lock.
+         * <p>
+         * Implementation Considerations
+         *
+         * A Lock implementation will usually impose restrictions on which thread can release
+         * a lock (typically only the holder of the lock can release it) and may throw an
+         * exception if the restriction is violated. Any restrictions and the exception
+         * type must be documented by that Lock implementation.
+         */
+        virtual void unlock() = 0;
+
+        /**
+         * Returns a new Condition instance that is bound to this Lock instance.
+         * <p>
+         * Before waiting on the condition the lock must be held by the current thread.
+         * A call to Condition.await() will atomically release the lock before waiting
+         * and re-acquire the lock before the wait returns.
+         * <p>
+         * Implementation Considerations
+         * <p>
+         * The exact operation of the Condition instance depends on the Lock implementation
+         * and must be documented by that implementation.
+         *
+         * @returns A new Condition instance for this Lock instance the caller must
+         *          delete the returned Condition object when done with it.
+         *
+         * @throws UnsupportedOperationException
+         *         if this Lock implementation does not support conditions
+         */
+        virtual Condition* newCondition()
+            throw ( decaf::lang::exceptions::UnsupportedOperationException ) = 0;
+
+    };
+
+}}}}
+
+#endif /*_DECAF_UTIL_CONCURRENT_LOCKS_LOCK_H_ */

Added: activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/ReadWriteLock.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/ReadWriteLock.h?rev=712296&view=auto
==============================================================================
--- activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/ReadWriteLock.h (added)
+++ activemq/activemq-cpp/trunk/src/main/decaf/util/concurrent/locks/ReadWriteLock.h Fri Nov
 7 14:41:02 2008
@@ -0,0 +1,107 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _DECAF_UTIL_CONCURRENT_LOCKS_READWRITELOCK_H_
+#define _DECAF_UTIL_CONCURRENT_LOCKS_READWRITELOCK_H_
+
+namespace decaf {
+namespace util {
+namespace concurrent {
+namespace locks {
+
+    /**
+     * A ReadWriteLock maintains a pair of associated locks, one for read-only operations
+     * and one for writing. The read lock may be held simultaneously by multiple reader
+     * threads, so long as there are no writers. The write lock is exclusive.
+     * <p>
+     * All ReadWriteLock implementations must guarantee that the memory synchronization
+     * effects of writeLock operations (as specified in the Lock interface) also hold with
+     * respect to the associated readLock. That is, a thread successfully acquiring the read
+     * lock will see all updates made upon previous release of the write lock.
+     * <p>
+     * A read-write lock allows for a greater level of concurrency in accessing shared data
+     * than that permitted by a mutual exclusion lock. It exploits the fact that while only
+     * a single thread at a time (a writer thread) can modify the shared data, in many cases
+     * any number of threads can concurrently read the data (hence reader threads). In theory,
+     * the increase in concurrency permitted by the use of a read-write lock will lead to
+     * performance improvements over the use of a mutual exclusion lock. In practice this
+     * increase in concurrency will only be fully realized on a multi-processor, and then
+     * only if the access patterns for the shared data are suitable.
+     * <p>
+     * Whether or not a read-write lock will improve performance over the use of a mutual
+     * exclusion lock depends on the frequency that the data is read compared to being
+     * modified, the duration of the read and write operations, and the contention for the
+     * data - that is, the number of threads that will try to read or write the data at the
+     * same time. For example, a collection that is initially populated with data and
+     * thereafter infrequently modified, while being frequently searched (such as a
+     * directory of some kind) is an ideal candidate for the use of a read-write lock.
+     * However, if updates become frequent then the data spends most of its time being
+     * exclusively locked and there is little, if any increase in concurrency. Further, if
+     * the read operations are too short the overhead of the read-write lock implementation
+     * (which is inherently more complex than a mutual exclusion lock) can dominate the
+     * execution cost, particularly as many read-write lock implementations still serialize
+     * all threads through a small section of code. Ultimately, only profiling and
+     * measurement will establish whether the use of a read-write lock is suitable for your
+     * application.
+     * <p>
+     * Although the basic operation of a read-write lock is straight-forward, there are many
+     * policy decisions that an implementation must make, which may affect the effectiveness
+     * of the read-write lock in a given application. Examples of these policies include:
+     *
+     *  * Determining whether to grant the read lock or the write lock, when both readers
and
+     *    writers are waiting, at the time that a writer releases the write lock. Writer
+     *    preference is common, as writes are expected to be short and infrequent. Reader
+     *    preference is less common as it can lead to lengthy delays for a write if the
+     *    readers are frequent and long-lived as expected. Fair, or "in-order" implementations
+     *    are also possible.
+     *  * Determining whether readers that request the read lock while a reader is active
and
+     *    a writer is waiting, are granted the read lock. Preference to the reader can delay
+     *    the writer indefinitely, while preference to the writer can reduce the potential
for
+     *    concurrency.
+     *  * Determining whether the locks are reentrant: can a thread with the write lock
+     *    reacquire it? Can it acquire a read lock while holding the write lock? Is the read
+     *    lock itself reentrant?
+     *  * Can the write lock be downgraded to a read lock without allowing an intervening
+     *    writer? Can a read lock be upgraded to a write lock, in preference to other waiting
+     *    readers or writers?
+     *
+     * You should consider all of these things when evaluating the suitability of a given
+     * implementation for your application.
+     *
+     * @since 1.0
+     */
+    class ReadWriteLock {
+    public:
+
+        virtual ~ReadWriteLock() {}
+
+        /**
+         * Returns the lock used for reading.
+         */
+        virtual Lock& readLock() = 0;
+
+        /**
+         * Returns the lock used for writing.
+         * @rerturns the lock used for writing.
+         */
+        virtual Lock& writeLock() = 0;
+
+    };
+
+}}}}
+
+#endif /*_DECAF_UTIL_CONCURRENT_LOCKS_READWRITELOCK_H_*/



Mime
View raw message