C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/util/ConcurrentMap.hpp

00001 /*
00002  * Copyright (c) 2000, 2020, Oracle and/or its affiliates.
00003  *
00004  * Licensed under the Universal Permissive License v 1.0 as shown at
00005  * http://oss.oracle.com/licenses/upl.
00006  */
00007 #ifndef COH_CONCURRENT_MAP_HPP
00008 #define COH_CONCURRENT_MAP_HPP
00009 
00010 #include "coherence/lang.ns"
00011 
00012 #include "coherence/util/Map.hpp"
00013 
00014 COH_OPEN_NAMESPACE2(coherence,util)
00015 
00016 
00017 /**
00018 * Map with additional concurrency features.
00019 *
00020 * @author jh  2008.03.05
00021 */
00022 class COH_EXPORT ConcurrentMap
00023     : public interface_spec<ConcurrentMap,
00024         implements<Map> >
00025     {
00026     // ----- handle definitions (needed for nested classes) -----------------
00027 
00028     public:
00029         typedef this_spec::Handle Handle;
00030         typedef this_spec::View   View;
00031         typedef this_spec::Holder Holder;
00032 
00033 
00034     // ----- ConcurrentMap interface ----------------------------------------
00035 
00036     public:
00037         /**
00038         * Attempt to lock the specified item within the specified period of
00039         * time.
00040         *
00041         * The item doesn't have to exist to be <i>locked</i>. While the item
00042         * is locked there is known to be a <i>lock holder</i> which has an
00043         * exclusive right to modify (calling put and remove methods) that
00044         * item.
00045         *
00046         * Lock holder is an abstract concept that depends on the
00047         * ConcurrentMap implementation. For example, holder could be a
00048         * process or a thread (or both).
00049         *
00050         * Locking strategy may vary for concrete implementations as well.
00051         * Lock could have an expiration time (this lock is sometimes called a
00052         * "lease") or be held indefinitely (until the lock holder
00053         * terminates).
00054         *
00055         * Some implementations may allow the entire map to be locked. If the
00056         * map is locked in such a way, then only a lock holder is allowed to
00057         * perform any of the "put" or "remove" operations. Pass the special
00058         * constant {@link #getLockAll()} as the <i>vKey</i> parameter to
00059         * indicate the map lock.
00060         *
00061         * @param vKey  key being locked
00062         * @param cWait the number of milliseconds to continue trying to
00063         *              obtain a lock; pass zero to return immediately; pass
00064         *              -1 to block the calling thread until the lock could be
00065         *              obtained
00066         *
00067         * @return true if the item was successfully locked within the
00068         *         specified time; false otherwise
00069         */
00070         virtual bool lock(Object::View vKey, int64_t cWait) const = 0;
00071 
00072         /**
00073         * Attempt to lock the specified item and return immediately.
00074         *
00075         * This method behaves exactly as if it simply performs the call
00076         * <tt>lock(vKey, 0)</tt>.
00077         *
00078         * @param vKey key being locked
00079         *
00080         * @return true if the item was successfully locked; false otherwise
00081         */
00082         virtual bool lock(Object::View vKey) const = 0;
00083 
00084         /**
00085         * Unlock the specified item. The item doesn't have to exist to be
00086         * <i>unlocked</i>. If the item is currently locked, only the
00087         * <i>holder</i> of the lock could successfully unlock it.
00088         *
00089         * @param vKey key being unlocked
00090         *
00091         * @return true if the item was successfully unlocked; false otherwise
00092         */
00093         virtual bool unlock(Object::View vKey) const = 0;
00094 
00095 
00096     // ----- inner class: LockBlock -----------------------------------------
00097 
00098     public:
00099         /**
00100         * The LockBlock allows for easy creation of ConcurrentMap::lock code.
00101         * It's used on conjunction with the COH_CACHE_LOCK macros.
00102         */
00103         class LockBlock
00104             {
00105             // ----- constructors ---------------------------------------
00106 
00107             public:
00108                 /**
00109                 * Construct a LockBlock that will lock the supplied map.
00110                 *
00111                 * @param hMap   the map to lock
00112                 * @param vKey   the Key to lock int he map
00113                 * @param cWait  the number of milliseconds to continue trying
00114                 *               to obtain a lock; pass zero to return
00115                 *               immediately; pass -1 to block the calling
00116                 *               thread until the lock could be obtained
00117                 */
00118                 LockBlock(ConcurrentMap::Handle hMap, Object::View vKey,
00119                         bool fTryLock, int64_t cWait = -1L);
00120 
00121                 /**
00122                 * Copy constructor used by the COH_CACHE_LOCK macros
00123                 */
00124                 LockBlock(const LockBlock& that);
00125 
00126                 /**
00127                 * Destroy an LockBlock object, exiting the associated map
00128                 */
00129                 ~LockBlock();
00130 
00131             // ----- LockBlock interface ---------------------------------
00132 
00133             public:
00134                 /**
00135                 * Boolean conversion for the COH_CACHE_LOCK macros
00136                 *
00137                 * @return true if it's a time based lock and false if no
00138                 */
00139                 operator bool() const;
00140 
00141             private:
00142                 /**
00143                 * Blocked assignment operator
00144                 */
00145                 const LockBlock& operator=(const LockBlock&);
00146 
00147                 /**
00148                 * Blocked dynamic allocation.
00149                 */
00150                 static void* operator new(size_t);
00151 
00152             // ----- data members ---------------------------------------
00153 
00154             protected:
00155                 /**
00156                 * Map to lock and unlock
00157                 */
00158                 mutable ConcurrentMap::Handle m_hMap; // on stack
00159 
00160                 /**
00161                 * Key to lock and unlock in the associated Map
00162                 */
00163                 const Object::View m_vKey; // on stack
00164 
00165                 /**
00166                 * Flag describing the type of lock being used
00167                 */
00168                 const bool m_fTryLock;
00169             };
00170 
00171 
00172     // ----- constants ------------------------------------------------------
00173 
00174     public:
00175         /**
00176         * Special key value indicating an intent to lock the entire map.
00177         */
00178         static Object::View getLockAll();
00179     };
00180 
00181 
00182 // ----- non-member operators and functions ---------------------------------
00183 
00184 
00185 /**
00186 * Macro for more readable cache locking blocks. See the ConcurrentMap docs
00187 * for more details.
00188 */
00189 #define COH_CACHE_LOCK(MAP, KEY) \
00190     if (coherence::util::ConcurrentMap::LockBlock COH_UNIQUE_IDENTIFIER(_coh_cache_lock_) \
00191         = coherence::util::ConcurrentMap::LockBlock(MAP, KEY, false, -1L)) \
00192         { \
00193         COH_THROW(coherence::lang::IllegalStateException::create()); \
00194         } \
00195         else
00196 
00197 
00198 #define COH_CACHE_TRYLOCK(MAP, KEY, TIME) \
00199     if (coherence::util::ConcurrentMap::LockBlock COH_UNIQUE_IDENTIFIER(_coh_cache_trylock_) \
00200             = coherence::util::ConcurrentMap::LockBlock( \
00201                 coherence::util::ConcurrentMap::LockBlock(MAP, KEY, true, TIME)))
00202 
00203 COH_CLOSE_NAMESPACE2
00204 
00205 #endif // COH_CONCURRENT_MAP_HPP
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.