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