annotate modules/javafx.web/src/main/native/Source/ThirdParty/icu/source/common/unifiedcache.h @ 11038:20a8447c71c6

8207159: Update ICU to version 62.1 Reviewed-by: mbilla, kcr, ghb
author arajkumar
date Fri, 24 Aug 2018 15:06:40 +0530
parents
children
rev   line source
arajkumar@11038 1 // © 2016 and later: Unicode, Inc. and others.
arajkumar@11038 2 // License & terms of use: http://www.unicode.org/copyright.html
arajkumar@11038 3 /*
arajkumar@11038 4 ******************************************************************************
arajkumar@11038 5 * Copyright (C) 2015, International Business Machines Corporation and
arajkumar@11038 6 * others. All Rights Reserved.
arajkumar@11038 7 ******************************************************************************
arajkumar@11038 8 *
arajkumar@11038 9 * File UNIFIEDCACHE.H - The ICU Unified cache.
arajkumar@11038 10 ******************************************************************************
arajkumar@11038 11 */
arajkumar@11038 12
arajkumar@11038 13 #ifndef __UNIFIED_CACHE_H__
arajkumar@11038 14 #define __UNIFIED_CACHE_H__
arajkumar@11038 15
arajkumar@11038 16 #include "utypeinfo.h" // for 'typeid' to work
arajkumar@11038 17
arajkumar@11038 18 #include "unicode/uobject.h"
arajkumar@11038 19 #include "unicode/locid.h"
arajkumar@11038 20 #include "sharedobject.h"
arajkumar@11038 21 #include "unicode/unistr.h"
arajkumar@11038 22 #include "cstring.h"
arajkumar@11038 23 #include "ustr_imp.h"
arajkumar@11038 24
arajkumar@11038 25 struct UHashtable;
arajkumar@11038 26 struct UHashElement;
arajkumar@11038 27
arajkumar@11038 28 U_NAMESPACE_BEGIN
arajkumar@11038 29
arajkumar@11038 30 class UnifiedCache;
arajkumar@11038 31
arajkumar@11038 32 /**
arajkumar@11038 33 * A base class for all cache keys.
arajkumar@11038 34 */
arajkumar@11038 35 class U_COMMON_API CacheKeyBase : public UObject {
arajkumar@11038 36 public:
arajkumar@11038 37 CacheKeyBase() : fCreationStatus(U_ZERO_ERROR), fIsMaster(FALSE) {}
arajkumar@11038 38
arajkumar@11038 39 /**
arajkumar@11038 40 * Copy constructor. Needed to support cloning.
arajkumar@11038 41 */
arajkumar@11038 42 CacheKeyBase(const CacheKeyBase &other)
arajkumar@11038 43 : UObject(other), fCreationStatus(other.fCreationStatus), fIsMaster(FALSE) { }
arajkumar@11038 44 virtual ~CacheKeyBase();
arajkumar@11038 45
arajkumar@11038 46 /**
arajkumar@11038 47 * Returns the hash code for this object.
arajkumar@11038 48 */
arajkumar@11038 49 virtual int32_t hashCode() const = 0;
arajkumar@11038 50
arajkumar@11038 51 /**
arajkumar@11038 52 * Clones this object polymorphically. Caller owns returned value.
arajkumar@11038 53 */
arajkumar@11038 54 virtual CacheKeyBase *clone() const = 0;
arajkumar@11038 55
arajkumar@11038 56 /**
arajkumar@11038 57 * Equality operator.
arajkumar@11038 58 */
arajkumar@11038 59 virtual UBool operator == (const CacheKeyBase &other) const = 0;
arajkumar@11038 60
arajkumar@11038 61 /**
arajkumar@11038 62 * Create a new object for this key. Called by cache on cache miss.
arajkumar@11038 63 * createObject must add a reference to the object it returns. Note
arajkumar@11038 64 * that getting an object from the cache and returning it without calling
arajkumar@11038 65 * removeRef on it satisfies this requirement. It can also return NULL
arajkumar@11038 66 * and set status to an error.
arajkumar@11038 67 *
arajkumar@11038 68 * @param creationContext the context in which the object is being
arajkumar@11038 69 * created. May be NULL.
arajkumar@11038 70 * @param status Implementations can return a failure here.
arajkumar@11038 71 * In addition, implementations may return a
arajkumar@11038 72 * non NULL object and set a warning status.
arajkumar@11038 73 */
arajkumar@11038 74 virtual const SharedObject *createObject(
arajkumar@11038 75 const void *creationContext, UErrorCode &status) const = 0;
arajkumar@11038 76
arajkumar@11038 77 /**
arajkumar@11038 78 * Writes a description of this key to buffer and returns buffer. Written
arajkumar@11038 79 * description is NULL terminated.
arajkumar@11038 80 */
arajkumar@11038 81 virtual char *writeDescription(char *buffer, int32_t bufSize) const = 0;
arajkumar@11038 82
arajkumar@11038 83 /**
arajkumar@11038 84 * Inequality operator.
arajkumar@11038 85 */
arajkumar@11038 86 UBool operator != (const CacheKeyBase &other) const {
arajkumar@11038 87 return !(*this == other);
arajkumar@11038 88 }
arajkumar@11038 89 private:
arajkumar@11038 90 mutable UErrorCode fCreationStatus;
arajkumar@11038 91 mutable UBool fIsMaster;
arajkumar@11038 92 friend class UnifiedCache;
arajkumar@11038 93 };
arajkumar@11038 94
arajkumar@11038 95
arajkumar@11038 96
arajkumar@11038 97 /**
arajkumar@11038 98 * Templated version of CacheKeyBase.
arajkumar@11038 99 * A key of type LocaleCacheKey<T> maps to a value of type T.
arajkumar@11038 100 */
arajkumar@11038 101 template<typename T>
arajkumar@11038 102 class CacheKey : public CacheKeyBase {
arajkumar@11038 103 public:
arajkumar@11038 104 virtual ~CacheKey() { }
arajkumar@11038 105 /**
arajkumar@11038 106 * The template parameter, T, determines the hash code returned.
arajkumar@11038 107 */
arajkumar@11038 108 virtual int32_t hashCode() const {
arajkumar@11038 109 const char *s = typeid(T).name();
arajkumar@11038 110 return ustr_hashCharsN(s, static_cast<int32_t>(uprv_strlen(s)));
arajkumar@11038 111 }
arajkumar@11038 112
arajkumar@11038 113 /**
arajkumar@11038 114 * Use the value type, T, as the description.
arajkumar@11038 115 */
arajkumar@11038 116 virtual char *writeDescription(char *buffer, int32_t bufLen) const {
arajkumar@11038 117 const char *s = typeid(T).name();
arajkumar@11038 118 uprv_strncpy(buffer, s, bufLen);
arajkumar@11038 119 buffer[bufLen - 1] = 0;
arajkumar@11038 120 return buffer;
arajkumar@11038 121 }
arajkumar@11038 122
arajkumar@11038 123 /**
arajkumar@11038 124 * Two objects are equal if they are of the same type.
arajkumar@11038 125 */
arajkumar@11038 126 virtual UBool operator == (const CacheKeyBase &other) const {
arajkumar@11038 127 return typeid(*this) == typeid(other);
arajkumar@11038 128 }
arajkumar@11038 129 };
arajkumar@11038 130
arajkumar@11038 131 /**
arajkumar@11038 132 * Cache key based on locale.
arajkumar@11038 133 * A key of type LocaleCacheKey<T> maps to a value of type T.
arajkumar@11038 134 */
arajkumar@11038 135 template<typename T>
arajkumar@11038 136 class LocaleCacheKey : public CacheKey<T> {
arajkumar@11038 137 protected:
arajkumar@11038 138 Locale fLoc;
arajkumar@11038 139 public:
arajkumar@11038 140 LocaleCacheKey(const Locale &loc) : fLoc(loc) {};
arajkumar@11038 141 LocaleCacheKey(const LocaleCacheKey<T> &other)
arajkumar@11038 142 : CacheKey<T>(other), fLoc(other.fLoc) { }
arajkumar@11038 143 virtual ~LocaleCacheKey() { }
arajkumar@11038 144 virtual int32_t hashCode() const {
arajkumar@11038 145 return (int32_t)(37u * (uint32_t)CacheKey<T>::hashCode() + (uint32_t)fLoc.hashCode());
arajkumar@11038 146 }
arajkumar@11038 147 virtual UBool operator == (const CacheKeyBase &other) const {
arajkumar@11038 148 // reflexive
arajkumar@11038 149 if (this == &other) {
arajkumar@11038 150 return TRUE;
arajkumar@11038 151 }
arajkumar@11038 152 if (!CacheKey<T>::operator == (other)) {
arajkumar@11038 153 return FALSE;
arajkumar@11038 154 }
arajkumar@11038 155 // We know this and other are of same class because operator== on
arajkumar@11038 156 // CacheKey returned true.
arajkumar@11038 157 const LocaleCacheKey<T> *fOther =
arajkumar@11038 158 static_cast<const LocaleCacheKey<T> *>(&other);
arajkumar@11038 159 return fLoc == fOther->fLoc;
arajkumar@11038 160 }
arajkumar@11038 161 virtual CacheKeyBase *clone() const {
arajkumar@11038 162 return new LocaleCacheKey<T>(*this);
arajkumar@11038 163 }
arajkumar@11038 164 virtual const T *createObject(
arajkumar@11038 165 const void *creationContext, UErrorCode &status) const;
arajkumar@11038 166 /**
arajkumar@11038 167 * Use the locale id as the description.
arajkumar@11038 168 */
arajkumar@11038 169 virtual char *writeDescription(char *buffer, int32_t bufLen) const {
arajkumar@11038 170 const char *s = fLoc.getName();
arajkumar@11038 171 uprv_strncpy(buffer, s, bufLen);
arajkumar@11038 172 buffer[bufLen - 1] = 0;
arajkumar@11038 173 return buffer;
arajkumar@11038 174 }
arajkumar@11038 175
arajkumar@11038 176 };
arajkumar@11038 177
arajkumar@11038 178 /**
arajkumar@11038 179 * The unified cache. A singleton type.
arajkumar@11038 180 * Design doc here:
arajkumar@11038 181 * https://docs.google.com/document/d/1RwGQJs4N4tawNbf809iYDRCvXoMKqDJihxzYt1ysmd8/edit?usp=sharing
arajkumar@11038 182 */
arajkumar@11038 183 class U_COMMON_API UnifiedCache : public UnifiedCacheBase {
arajkumar@11038 184 public:
arajkumar@11038 185 /**
arajkumar@11038 186 * @internal
arajkumar@11038 187 * Do not call directly. Instead use UnifiedCache::getInstance() as
arajkumar@11038 188 * there should be only one UnifiedCache in an application.
arajkumar@11038 189 */
arajkumar@11038 190 UnifiedCache(UErrorCode &status);
arajkumar@11038 191
arajkumar@11038 192 /**
arajkumar@11038 193 * Return a pointer to the global cache instance.
arajkumar@11038 194 */
arajkumar@11038 195 static UnifiedCache *getInstance(UErrorCode &status);
arajkumar@11038 196
arajkumar@11038 197 /**
arajkumar@11038 198 * Fetches a value from the cache by key. Equivalent to
arajkumar@11038 199 * get(key, NULL, ptr, status);
arajkumar@11038 200 */
arajkumar@11038 201 template<typename T>
arajkumar@11038 202 void get(
arajkumar@11038 203 const CacheKey<T>& key,
arajkumar@11038 204 const T *&ptr,
arajkumar@11038 205 UErrorCode &status) const {
arajkumar@11038 206 get(key, NULL, ptr, status);
arajkumar@11038 207 }
arajkumar@11038 208
arajkumar@11038 209 /**
arajkumar@11038 210 * Fetches value from the cache by key.
arajkumar@11038 211 *
arajkumar@11038 212 * @param key the cache key.
arajkumar@11038 213 * @param creationContext passed verbatim to createObject method of key
arajkumar@11038 214 * @param ptr On entry, ptr must be NULL or be included if
arajkumar@11038 215 * the reference count of the object it points
arajkumar@11038 216 * to. On exit, ptr points to the fetched object
arajkumar@11038 217 * from the cache or is left unchanged on
arajkumar@11038 218 * failure. Caller must call removeRef on ptr
arajkumar@11038 219 * if set to a non NULL value.
arajkumar@11038 220 * @param status Any error returned here. May be set to a
arajkumar@11038 221 * warning value even if ptr is set.
arajkumar@11038 222 */
arajkumar@11038 223 template<typename T>
arajkumar@11038 224 void get(
arajkumar@11038 225 const CacheKey<T>& key,
arajkumar@11038 226 const void *creationContext,
arajkumar@11038 227 const T *&ptr,
arajkumar@11038 228 UErrorCode &status) const {
arajkumar@11038 229 if (U_FAILURE(status)) {
arajkumar@11038 230 return;
arajkumar@11038 231 }
arajkumar@11038 232 UErrorCode creationStatus = U_ZERO_ERROR;
arajkumar@11038 233 const SharedObject *value = NULL;
arajkumar@11038 234 _get(key, value, creationContext, creationStatus);
arajkumar@11038 235 const T *tvalue = (const T *) value;
arajkumar@11038 236 if (U_SUCCESS(creationStatus)) {
arajkumar@11038 237 SharedObject::copyPtr(tvalue, ptr);
arajkumar@11038 238 }
arajkumar@11038 239 SharedObject::clearPtr(tvalue);
arajkumar@11038 240 // Take care not to overwrite a warning status passed in with
arajkumar@11038 241 // another warning or U_ZERO_ERROR.
arajkumar@11038 242 if (status == U_ZERO_ERROR || U_FAILURE(creationStatus)) {
arajkumar@11038 243 status = creationStatus;
arajkumar@11038 244 }
arajkumar@11038 245 }
arajkumar@11038 246
arajkumar@11038 247 #ifdef UNIFIED_CACHE_DEBUG
arajkumar@11038 248 /**
arajkumar@11038 249 * Dumps the contents of this cache to standard error. Used for testing of
arajkumar@11038 250 * cache only.
arajkumar@11038 251 */
arajkumar@11038 252 void dumpContents() const;
arajkumar@11038 253 #endif
arajkumar@11038 254
arajkumar@11038 255 /**
arajkumar@11038 256 * Convenience method to get a value of type T from cache for a
arajkumar@11038 257 * particular locale with creationContext == NULL.
arajkumar@11038 258 * @param loc the locale
arajkumar@11038 259 * @param ptr On entry, must be NULL or included in the ref count
arajkumar@11038 260 * of the object to which it points.
arajkumar@11038 261 * On exit, fetched value stored here or is left
arajkumar@11038 262 * unchanged on failure. Caller must call removeRef on
arajkumar@11038 263 * ptr if set to a non NULL value.
arajkumar@11038 264 * @param status Any error returned here. May be set to a
arajkumar@11038 265 * warning value even if ptr is set.
arajkumar@11038 266 */
arajkumar@11038 267 template<typename T>
arajkumar@11038 268 static void getByLocale(
arajkumar@11038 269 const Locale &loc, const T *&ptr, UErrorCode &status) {
arajkumar@11038 270 const UnifiedCache *cache = getInstance(status);
arajkumar@11038 271 if (U_FAILURE(status)) {
arajkumar@11038 272 return;
arajkumar@11038 273 }
arajkumar@11038 274 cache->get(LocaleCacheKey<T>(loc), ptr, status);
arajkumar@11038 275 }
arajkumar@11038 276
arajkumar@11038 277 #ifdef UNIFIED_CACHE_DEBUG
arajkumar@11038 278 /**
arajkumar@11038 279 * Dumps the cache contents to stderr. For testing only.
arajkumar@11038 280 */
arajkumar@11038 281 static void dump();
arajkumar@11038 282 #endif
arajkumar@11038 283
arajkumar@11038 284 /**
arajkumar@11038 285 * Returns the number of keys in this cache. For testing only.
arajkumar@11038 286 */
arajkumar@11038 287 int32_t keyCount() const;
arajkumar@11038 288
arajkumar@11038 289 /**
arajkumar@11038 290 * Removes any values from cache that are not referenced outside
arajkumar@11038 291 * the cache.
arajkumar@11038 292 */
arajkumar@11038 293 void flush() const;
arajkumar@11038 294
arajkumar@11038 295 /**
arajkumar@11038 296 * Configures at what point evcition of unused entries will begin.
arajkumar@11038 297 * Eviction is triggered whenever the number of evictable keys exeeds
arajkumar@11038 298 * BOTH count AND (number of in-use items) * (percentageOfInUseItems / 100).
arajkumar@11038 299 * Once the number of unused entries drops below one of these,
arajkumar@11038 300 * eviction ceases. Because eviction happens incrementally,
arajkumar@11038 301 * the actual unused entry count may exceed both these numbers
arajkumar@11038 302 * from time to time.
arajkumar@11038 303 *
arajkumar@11038 304 * A cache entry is defined as unused if it is not essential to guarantee
arajkumar@11038 305 * that for a given key X, the cache returns the same reference to the
arajkumar@11038 306 * same value as long as the client already holds a reference to that
arajkumar@11038 307 * value.
arajkumar@11038 308 *
arajkumar@11038 309 * If this method is never called, the default settings are 1000 and 100%.
arajkumar@11038 310 *
arajkumar@11038 311 * Although this method is thread-safe, it is designed to be called at
arajkumar@11038 312 * application startup. If it is called in the middle of execution, it
arajkumar@11038 313 * will have no immediate effect on the cache. However over time, the
arajkumar@11038 314 * cache will perform eviction slices in an attempt to honor the new
arajkumar@11038 315 * settings.
arajkumar@11038 316 *
arajkumar@11038 317 * If a client already holds references to many different unique values
arajkumar@11038 318 * in the cache such that the number of those unique values far exeeds
arajkumar@11038 319 * "count" then the cache may not be able to maintain this maximum.
arajkumar@11038 320 * However, if this happens, the cache still guarantees that the number of
arajkumar@11038 321 * unused entries will remain only a small percentage of the total cache
arajkumar@11038 322 * size.
arajkumar@11038 323 *
arajkumar@11038 324 * If the parameters passed are negative, setEvctionPolicy sets status to
arajkumar@11038 325 * U_ILLEGAL_ARGUMENT_ERROR.
arajkumar@11038 326 */
arajkumar@11038 327 void setEvictionPolicy(
arajkumar@11038 328 int32_t count, int32_t percentageOfInUseItems, UErrorCode &status);
arajkumar@11038 329
arajkumar@11038 330
arajkumar@11038 331 /**
arajkumar@11038 332 * Returns how many entries have been auto evicted during the lifetime
arajkumar@11038 333 * of this cache. This only includes auto evicted entries, not
arajkumar@11038 334 * entries evicted because of a call to flush().
arajkumar@11038 335 */
arajkumar@11038 336 int64_t autoEvictedCount() const;
arajkumar@11038 337
arajkumar@11038 338 /**
arajkumar@11038 339 * Returns the unused entry count in this cache. For testing only,
arajkumar@11038 340 * Regular clients will not need this.
arajkumar@11038 341 */
arajkumar@11038 342 int32_t unusedCount() const;
arajkumar@11038 343
arajkumar@11038 344 virtual void handleUnreferencedObject() const;
arajkumar@11038 345 virtual ~UnifiedCache();
arajkumar@11038 346
arajkumar@11038 347 private:
arajkumar@11038 348 UHashtable *fHashtable;
arajkumar@11038 349 mutable int32_t fEvictPos;
arajkumar@11038 350 mutable int32_t fNumValuesTotal;
arajkumar@11038 351 mutable int32_t fNumValuesInUse;
arajkumar@11038 352 int32_t fMaxUnused;
arajkumar@11038 353 int32_t fMaxPercentageOfInUse;
arajkumar@11038 354 mutable int64_t fAutoEvictedCount;
arajkumar@11038 355 SharedObject *fNoValue;
arajkumar@11038 356
arajkumar@11038 357 UnifiedCache(const UnifiedCache &other);
arajkumar@11038 358 UnifiedCache &operator=(const UnifiedCache &other);
arajkumar@11038 359
arajkumar@11038 360 /**
arajkumar@11038 361 * Flushes the contents of the cache. If cache values hold references to other
arajkumar@11038 362 * cache values then _flush should be called in a loop until it returns FALSE.
arajkumar@11038 363 *
arajkumar@11038 364 * On entry, gCacheMutex must be held.
arajkumar@11038 365 * On exit, those values with are evictable are flushed.
arajkumar@11038 366 *
arajkumar@11038 367 * @param all if false flush evictable items only, which are those with no external
arajkumar@11038 368 * references, plus those that can be safely recreated.<br>
arajkumar@11038 369 * if true, flush all elements. Any values (sharedObjects) with remaining
arajkumar@11038 370 * hard (external) references are not deleted, but are detached from
arajkumar@11038 371 * the cache, so that a subsequent removeRefs can delete them.
arajkumar@11038 372 * _flush is not thread safe when all is true.
arajkumar@11038 373 * @return TRUE if any value in cache was flushed or FALSE otherwise.
arajkumar@11038 374 */
arajkumar@11038 375 UBool _flush(UBool all) const;
arajkumar@11038 376
arajkumar@11038 377 /**
arajkumar@11038 378 * Gets value out of cache.
arajkumar@11038 379 * On entry. gCacheMutex must not be held. value must be NULL. status
arajkumar@11038 380 * must be U_ZERO_ERROR.
arajkumar@11038 381 * On exit. value and status set to what is in cache at key or on cache
arajkumar@11038 382 * miss the key's createObject() is called and value and status are set to
arajkumar@11038 383 * the result of that. In this latter case, best effort is made to add the
arajkumar@11038 384 * value and status to the cache. If createObject() fails to create a value,
arajkumar@11038 385 * fNoValue is stored in cache, and value is set to NULL. Caller must call
arajkumar@11038 386 * removeRef on value if non NULL.
arajkumar@11038 387 */
arajkumar@11038 388 void _get(
arajkumar@11038 389 const CacheKeyBase &key,
arajkumar@11038 390 const SharedObject *&value,
arajkumar@11038 391 const void *creationContext,
arajkumar@11038 392 UErrorCode &status) const;
arajkumar@11038 393
arajkumar@11038 394 /**
arajkumar@11038 395 * Attempts to fetch value and status for key from cache.
arajkumar@11038 396 * On entry, gCacheMutex must not be held value must be NULL and status must
arajkumar@11038 397 * be U_ZERO_ERROR.
arajkumar@11038 398 * On exit, either returns FALSE (In this
arajkumar@11038 399 * case caller should try to create the object) or returns TRUE with value
arajkumar@11038 400 * pointing to the fetched value and status set to fetched status. When
arajkumar@11038 401 * FALSE is returned status may be set to failure if an in progress hash
arajkumar@11038 402 * entry could not be made but value will remain unchanged. When TRUE is
arajkumar@11038 403 * returned, caller must call removeRef() on value.
arajkumar@11038 404 */
arajkumar@11038 405 UBool _poll(
arajkumar@11038 406 const CacheKeyBase &key,
arajkumar@11038 407 const SharedObject *&value,
arajkumar@11038 408 UErrorCode &status) const;
arajkumar@11038 409
arajkumar@11038 410 /**
arajkumar@11038 411 * Places a new value and creationStatus in the cache for the given key.
arajkumar@11038 412 * On entry, gCacheMutex must be held. key must not exist in the cache.
arajkumar@11038 413 * On exit, value and creation status placed under key. Soft reference added
arajkumar@11038 414 * to value on successful add. On error sets status.
arajkumar@11038 415 */
arajkumar@11038 416 void _putNew(
arajkumar@11038 417 const CacheKeyBase &key,
arajkumar@11038 418 const SharedObject *value,
arajkumar@11038 419 const UErrorCode creationStatus,
arajkumar@11038 420 UErrorCode &status) const;
arajkumar@11038 421
arajkumar@11038 422 /**
arajkumar@11038 423 * Places value and status at key if there is no value at key or if cache
arajkumar@11038 424 * entry for key is in progress. Otherwise, it leaves the current value and
arajkumar@11038 425 * status there.
arajkumar@11038 426 *
arajkumar@11038 427 * On entry. gCacheMutex must not be held. Value must be
arajkumar@11038 428 * included in the reference count of the object to which it points.
arajkumar@11038 429 *
arajkumar@11038 430 * On exit, value and status are changed to what was already in the cache if
arajkumar@11038 431 * something was there and not in progress. Otherwise, value and status are left
arajkumar@11038 432 * unchanged in which case they are placed in the cache on a best-effort basis.
arajkumar@11038 433 * Caller must call removeRef() on value.
arajkumar@11038 434 */
arajkumar@11038 435 void _putIfAbsentAndGet(
arajkumar@11038 436 const CacheKeyBase &key,
arajkumar@11038 437 const SharedObject *&value,
arajkumar@11038 438 UErrorCode &status) const;
arajkumar@11038 439
arajkumar@11038 440 /**
arajkumar@11038 441 * Returns the next element in the cache round robin style.
arajkumar@11038 442 * Returns nullptr if the cache is empty.
arajkumar@11038 443 * On entry, gCacheMutex must be held.
arajkumar@11038 444 */
arajkumar@11038 445 const UHashElement *_nextElement() const;
arajkumar@11038 446
arajkumar@11038 447 /**
arajkumar@11038 448 * Return the number of cache items that would need to be evicted
arajkumar@11038 449 * to bring usage into conformance with eviction policy.
arajkumar@11038 450 *
arajkumar@11038 451 * An item corresponds to an entry in the hash table, a hash table element.
arajkumar@11038 452 *
arajkumar@11038 453 * On entry, gCacheMutex must be held.
arajkumar@11038 454 */
arajkumar@11038 455 int32_t _computeCountOfItemsToEvict() const;
arajkumar@11038 456
arajkumar@11038 457 /**
arajkumar@11038 458 * Run an eviction slice.
arajkumar@11038 459 * On entry, gCacheMutex must be held.
arajkumar@11038 460 * _runEvictionSlice runs a slice of the evict pipeline by examining the next
arajkumar@11038 461 * 10 entries in the cache round robin style evicting them if they are eligible.
arajkumar@11038 462 */
arajkumar@11038 463 void _runEvictionSlice() const;
arajkumar@11038 464
arajkumar@11038 465 /**
arajkumar@11038 466 * Register a master cache entry. A master key is the first key to create
arajkumar@11038 467 * a given SharedObject value. Subsequent keys whose create function
arajkumar@11038 468 * produce referneces to an already existing SharedObject are not masters -
arajkumar@11038 469 * they can be evicted and subsequently recreated.
arajkumar@11038 470 *
arajkumar@11038 471 * On entry, gCacheMutex must be held.
arajkumar@11038 472 * On exit, items in use count incremented, entry is marked as a master
arajkumar@11038 473 * entry, and value registered with cache so that subsequent calls to
arajkumar@11038 474 * addRef() and removeRef() on it correctly interact with the cache.
arajkumar@11038 475 */
arajkumar@11038 476 void _registerMaster(const CacheKeyBase *theKey, const SharedObject *value) const;
arajkumar@11038 477
arajkumar@11038 478 /**
arajkumar@11038 479 * Store a value and creation error status in given hash entry.
arajkumar@11038 480 * On entry, gCacheMutex must be held. Hash entry element must be in progress.
arajkumar@11038 481 * value must be non NULL.
arajkumar@11038 482 * On Exit, soft reference added to value. value and status stored in hash
arajkumar@11038 483 * entry. Soft reference removed from previous stored value. Waiting
arajkumar@11038 484 * threads notified.
arajkumar@11038 485 */
arajkumar@11038 486 void _put(
arajkumar@11038 487 const UHashElement *element,
arajkumar@11038 488 const SharedObject *value,
arajkumar@11038 489 const UErrorCode status) const;
arajkumar@11038 490 /**
arajkumar@11038 491 * Remove a soft reference, and delete the SharedObject if no references remain.
arajkumar@11038 492 * To be used from within the UnifiedCache implementation only.
arajkumar@11038 493 * gCacheMutex must be held by caller.
arajkumar@11038 494 * @param value the SharedObject to be acted on.
arajkumar@11038 495 */
arajkumar@11038 496 void removeSoftRef(const SharedObject *value) const;
arajkumar@11038 497
arajkumar@11038 498 /**
arajkumar@11038 499 * Increment the hard reference count of the given SharedObject.
arajkumar@11038 500 * gCacheMutex must be held by the caller.
arajkumar@11038 501 * Update numValuesEvictable on transitions between zero and one reference.
arajkumar@11038 502 *
arajkumar@11038 503 * @param value The SharedObject to be referenced.
arajkumar@11038 504 * @return the hard reference count after the addition.
arajkumar@11038 505 */
arajkumar@11038 506 int32_t addHardRef(const SharedObject *value) const;
arajkumar@11038 507
arajkumar@11038 508 /**
arajkumar@11038 509 * Decrement the hard reference count of the given SharedObject.
arajkumar@11038 510 * gCacheMutex must be held by the caller.
arajkumar@11038 511 * Update numValuesEvictable on transitions between one and zero reference.
arajkumar@11038 512 *
arajkumar@11038 513 * @param value The SharedObject to be referenced.
arajkumar@11038 514 * @return the hard reference count after the removal.
arajkumar@11038 515 */
arajkumar@11038 516 int32_t removeHardRef(const SharedObject *value) const;
arajkumar@11038 517
arajkumar@11038 518
arajkumar@11038 519 #ifdef UNIFIED_CACHE_DEBUG
arajkumar@11038 520 void _dumpContents() const;
arajkumar@11038 521 #endif
arajkumar@11038 522
arajkumar@11038 523 /**
arajkumar@11038 524 * Fetch value and error code from a particular hash entry.
arajkumar@11038 525 * On entry, gCacheMutex must be held. value must be either NULL or must be
arajkumar@11038 526 * included in the ref count of the object to which it points.
arajkumar@11038 527 * On exit, value and status set to what is in the hash entry. Caller must
arajkumar@11038 528 * eventually call removeRef on value.
arajkumar@11038 529 * If hash entry is in progress, value will be set to gNoValue and status will
arajkumar@11038 530 * be set to U_ZERO_ERROR.
arajkumar@11038 531 */
arajkumar@11038 532 void _fetch(const UHashElement *element, const SharedObject *&value,
arajkumar@11038 533 UErrorCode &status) const;
arajkumar@11038 534
arajkumar@11038 535 /**
arajkumar@11038 536 * Determine if given hash entry is in progress.
arajkumar@11038 537 * On entry, gCacheMutex must be held.
arajkumar@11038 538 */
arajkumar@11038 539 UBool _inProgress(const UHashElement *element) const;
arajkumar@11038 540
arajkumar@11038 541 /**
arajkumar@11038 542 * Determine if given hash entry is in progress.
arajkumar@11038 543 * On entry, gCacheMutex must be held.
arajkumar@11038 544 */
arajkumar@11038 545 UBool _inProgress(const SharedObject *theValue, UErrorCode creationStatus) const;
arajkumar@11038 546
arajkumar@11038 547 /**
arajkumar@11038 548 * Determine if given hash entry is eligible for eviction.
arajkumar@11038 549 * On entry, gCacheMutex must be held.
arajkumar@11038 550 */
arajkumar@11038 551 UBool _isEvictable(const UHashElement *element) const;
arajkumar@11038 552 };
arajkumar@11038 553
arajkumar@11038 554 U_NAMESPACE_END
arajkumar@11038 555
arajkumar@11038 556 #endif