Нет описания

AWSTMCache.h 6.5KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177
  1. /**
  2. `TMCache` is a thread safe key/value store designed for persisting temporary objects that are expensive to
  3. reproduce, such as downloaded data or the results of slow processing. It is comprised of two self-similar
  4. stores, one in memory (<TMMemoryCache>) and one on disk (<TMDiskCache>).
  5. `TMCache` itself actually does very little; its main function is providing a front end for a common use case:
  6. a small, fast memory cache that asynchronously persists itself to a large, slow disk cache. When objects are
  7. removed from the memory cache in response to an "apocalyptic" event they remain in the disk cache and are
  8. repopulated in memory the next time they are accessed. `TMCache` also does the tedious work of creating a
  9. dispatch group to wait for both caches to finish their operations without blocking each other.
  10. The parallel caches are accessible as public properties (<memoryCache> and <diskCache>) and can be manipulated
  11. separately if necessary. See the docs for <TMMemoryCache> and <TMDiskCache> for more details.
  12. */
  13. #import <Foundation/Foundation.h>
  14. #import "AWSTMDiskCache.h"
  15. #import "AWSTMMemoryCache.h"
  16. @class AWSTMCache;
  17. typedef void (^AWSTMCacheBlock)(AWSTMCache *cache);
  18. typedef void (^AWSTMCacheObjectBlock)(AWSTMCache *cache, NSString *key, id object);
  19. @interface AWSTMCache : NSObject
  20. #pragma mark -
  21. /// @name Core
  22. /**
  23. The name of this cache, used to create the <diskCache> and also appearing in stack traces.
  24. */
  25. @property (readonly) NSString *name;
  26. /**
  27. A concurrent queue on which blocks passed to the asynchronous access methods are run.
  28. */
  29. @property (readonly) dispatch_queue_t queue;
  30. /**
  31. Synchronously retrieves the total byte count of the <diskCache> on the shared disk queue.
  32. */
  33. @property (readonly) NSUInteger diskByteCount;
  34. /**
  35. The underlying disk cache, see <TMDiskCache> for additional configuration and trimming options.
  36. */
  37. @property (readonly) AWSTMDiskCache *diskCache;
  38. /**
  39. The underlying memory cache, see <TMMemoryCache> for additional configuration and trimming options.
  40. */
  41. @property (readonly) AWSTMMemoryCache *memoryCache;
  42. #pragma mark -
  43. /// @name Initialization
  44. /**
  45. A shared cache.
  46. @result The shared singleton cache instance.
  47. */
  48. + (instancetype)sharedCache;
  49. /**
  50. Multiple instances with the same name are allowed and can safely access
  51. the same data on disk thanks to the magic of seriality. Also used to create the <diskCache>.
  52. @see name
  53. @param name The name of the cache.
  54. @result A new cache with the specified name.
  55. */
  56. - (instancetype)initWithName:(NSString *)name;
  57. /**
  58. The designated initializer. Multiple instances with the same name are allowed and can safely access
  59. the same data on disk thanks to the magic of seriality. Also used to create the <diskCache>.
  60. @see name
  61. @param name The name of the cache.
  62. @param rootPath The path of the cache on disk.
  63. @result A new cache with the specified name.
  64. */
  65. - (instancetype)initWithName:(NSString *)name rootPath:(NSString *)rootPath;
  66. #pragma mark -
  67. /// @name Asynchronous Methods
  68. /**
  69. Retrieves the object for the specified key. This method returns immediately and executes the passed
  70. block after the object is available, potentially in parallel with other blocks on the <queue>.
  71. @param key The key associated with the requested object.
  72. @param block A block to be executed concurrently when the object is available.
  73. */
  74. - (void)objectForKey:(NSString *)key block:(AWSTMCacheObjectBlock)block;
  75. /**
  76. Stores an object in the cache for the specified key. This method returns immediately and executes the
  77. passed block after the object has been stored, potentially in parallel with other blocks on the <queue>.
  78. @param object An object to store in the cache.
  79. @param key A key to associate with the object. This string will be copied.
  80. @param block A block to be executed concurrently after the object has been stored, or nil.
  81. */
  82. - (void)setObject:(id <NSCoding>)object forKey:(NSString *)key block:(AWSTMCacheObjectBlock)block;
  83. /**
  84. Removes the object for the specified key. This method returns immediately and executes the passed
  85. block after the object has been removed, potentially in parallel with other blocks on the <queue>.
  86. @param key The key associated with the object to be removed.
  87. @param block A block to be executed concurrently after the object has been removed, or nil.
  88. */
  89. - (void)removeObjectForKey:(NSString *)key block:(AWSTMCacheObjectBlock)block;
  90. /**
  91. Removes all objects from the cache that have not been used since the specified date. This method returns immediately and
  92. executes the passed block after the cache has been trimmed, potentially in parallel with other blocks on the <queue>.
  93. @param date Objects that haven't been accessed since this date are removed from the cache.
  94. @param block A block to be executed concurrently after the cache has been trimmed, or nil.
  95. */
  96. - (void)trimToDate:(NSDate *)date block:(AWSTMCacheBlock)block;
  97. /**
  98. Removes all objects from the cache.This method returns immediately and executes the passed block after the
  99. cache has been cleared, potentially in parallel with other blocks on the <queue>.
  100. @param block A block to be executed concurrently after the cache has been cleared, or nil.
  101. */
  102. - (void)removeAllObjects:(AWSTMCacheBlock)block;
  103. #pragma mark -
  104. /// @name Synchronous Methods
  105. /**
  106. Retrieves the object for the specified key. This method blocks the calling thread until the object is available.
  107. @see objectForKey:block:
  108. @param key The key associated with the object.
  109. @result The object for the specified key.
  110. */
  111. - (id)objectForKey:(NSString *)key;
  112. /**
  113. Stores an object in the cache for the specified key. This method blocks the calling thread until the object has been set.
  114. @see setObject:forKey:block:
  115. @param object An object to store in the cache.
  116. @param key A key to associate with the object. This string will be copied.
  117. */
  118. - (void)setObject:(id <NSCoding>)object forKey:(NSString *)key;
  119. /**
  120. Removes the object for the specified key. This method blocks the calling thread until the object
  121. has been removed.
  122. @param key The key associated with the object to be removed.
  123. */
  124. - (void)removeObjectForKey:(NSString *)key;
  125. /**
  126. Removes all objects from the cache that have not been used since the specified date.
  127. This method blocks the calling thread until the cache has been trimmed.
  128. @param date Objects that haven't been accessed since this date are removed from the cache.
  129. */
  130. - (void)trimToDate:(NSDate *)date;
  131. /**
  132. Removes all objects from the cache. This method blocks the calling thread until the cache has been cleared.
  133. */
  134. - (void)removeAllObjects;
  135. @end