YYCache.h 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192
  1. //
  2. // YYCache.h
  3. // YYKit <https://github.com/ibireme/YYKit>
  4. //
  5. // Created by ibireme on 15/2/13.
  6. // Copyright (c) 2015 ibireme.
  7. //
  8. // This source code is licensed under the MIT-style license found in the
  9. // LICENSE file in the root directory of this source tree.
  10. //
  11. #import <Foundation/Foundation.h>
  12. @class YYMemoryCache, YYDiskCache;
  13. NS_ASSUME_NONNULL_BEGIN
  14. /**
  15. `YYCache` is a thread safe key-value cache.
  16. It use `YYMemoryCache` to store objects in a small and fast memory cache,
  17. and use `YYDiskCache` to persisting objects to a large and slow disk cache.
  18. See `YYMemoryCache` and `YYDiskCache` for more information.
  19. */
  20. @interface YYCache : NSObject
  21. /** The name of the cache, readonly. */
  22. @property (copy, readonly) NSString *name;
  23. /** The underlying memory cache. see `YYMemoryCache` for more information.*/
  24. @property (strong, readonly) YYMemoryCache *memoryCache;
  25. /** The underlying disk cache. see `YYDiskCache` for more information.*/
  26. @property (strong, readonly) YYDiskCache *diskCache;
  27. /**
  28. Create a new instance with the specified name.
  29. Multiple instances with the same name will make the cache unstable.
  30. @param name The name of the cache. It will create a dictionary with the name in
  31. the app's caches dictionary for disk cache. Once initialized you should not
  32. read and write to this directory.
  33. @result A new cache object, or nil if an error occurs.
  34. */
  35. - (nullable instancetype)initWithName:(NSString *)name;
  36. /**
  37. Create a new instance with the specified path.
  38. Multiple instances with the same name will make the cache unstable.
  39. @param path Full path of a directory in which the cache will write data.
  40. Once initialized you should not read and write to this directory.
  41. @result A new cache object, or nil if an error occurs.
  42. */
  43. - (nullable instancetype)initWithPath:(NSString *)path NS_DESIGNATED_INITIALIZER;
  44. /**
  45. Convenience Initializers
  46. Create a new instance with the specified name.
  47. Multiple instances with the same name will make the cache unstable.
  48. @param name The name of the cache. It will create a dictionary with the name in
  49. the app's caches dictionary for disk cache. Once initialized you should not
  50. read and write to this directory.
  51. @result A new cache object, or nil if an error occurs.
  52. */
  53. + (nullable instancetype)cacheWithName:(NSString *)name;
  54. /**
  55. Convenience Initializers
  56. Create a new instance with the specified path.
  57. Multiple instances with the same name will make the cache unstable.
  58. @param path Full path of a directory in which the cache will write data.
  59. Once initialized you should not read and write to this directory.
  60. @result A new cache object, or nil if an error occurs.
  61. */
  62. + (nullable instancetype)cacheWithPath:(NSString *)path;
  63. - (instancetype)init UNAVAILABLE_ATTRIBUTE;
  64. + (instancetype)new UNAVAILABLE_ATTRIBUTE;
  65. #pragma mark - Access Methods
  66. ///=============================================================================
  67. /// @name Access Methods
  68. ///=============================================================================
  69. /**
  70. Returns a boolean value that indicates whether a given key is in cache.
  71. This method may blocks the calling thread until file read finished.
  72. @param key A string identifying the value. If nil, just return NO.
  73. @return Whether the key is in cache.
  74. */
  75. - (BOOL)containsObjectForKey:(NSString *)key;
  76. /**
  77. Returns a boolean value with the block that indicates whether a given key is in cache.
  78. This method returns immediately and invoke the passed block in background queue
  79. when the operation finished.
  80. @param key A string identifying the value. If nil, just return NO.
  81. @param block A block which will be invoked in background queue when finished.
  82. */
  83. - (void)containsObjectForKey:(NSString *)key withBlock:(nullable void(^)(NSString *key, BOOL contains))block;
  84. /**
  85. Returns the value associated with a given key.
  86. This method may blocks the calling thread until file read finished.
  87. @param key A string identifying the value. If nil, just return nil.
  88. @return The value associated with key, or nil if no value is associated with key.
  89. */
  90. - (nullable id<NSCoding>)objectForKey:(NSString *)key;
  91. /**
  92. Returns the value associated with a given key.
  93. This method returns immediately and invoke the passed block in background queue
  94. when the operation finished.
  95. @param key A string identifying the value. If nil, just return nil.
  96. @param block A block which will be invoked in background queue when finished.
  97. */
  98. - (void)objectForKey:(NSString *)key withBlock:(nullable void(^)(NSString *key, id<NSCoding> object))block;
  99. /**
  100. Sets the value of the specified key in the cache.
  101. This method may blocks the calling thread until file write finished.
  102. @param object The object to be stored in the cache. If nil, it calls `removeObjectForKey:`.
  103. @param key The key with which to associate the value. If nil, this method has no effect.
  104. */
  105. - (void)setObject:(nullable id<NSCoding>)object forKey:(NSString *)key;
  106. /**
  107. Sets the value of the specified key in the cache.
  108. This method returns immediately and invoke the passed block in background queue
  109. when the operation finished.
  110. @param object The object to be stored in the cache. If nil, it calls `removeObjectForKey:`.
  111. @param block A block which will be invoked in background queue when finished.
  112. */
  113. - (void)setObject:(nullable id<NSCoding>)object forKey:(NSString *)key withBlock:(nullable void(^)(void))block;
  114. /**
  115. Removes the value of the specified key in the cache.
  116. This method may blocks the calling thread until file delete finished.
  117. @param key The key identifying the value to be removed. If nil, this method has no effect.
  118. */
  119. - (void)removeObjectForKey:(NSString *)key;
  120. /**
  121. Removes the value of the specified key in the cache.
  122. This method returns immediately and invoke the passed block in background queue
  123. when the operation finished.
  124. @param key The key identifying the value to be removed. If nil, this method has no effect.
  125. @param block A block which will be invoked in background queue when finished.
  126. */
  127. - (void)removeObjectForKey:(NSString *)key withBlock:(nullable void(^)(NSString *key))block;
  128. /**
  129. Empties the cache.
  130. This method may blocks the calling thread until file delete finished.
  131. */
  132. - (void)removeAllObjects;
  133. /**
  134. Empties the cache.
  135. This method returns immediately and invoke the passed block in background queue
  136. when the operation finished.
  137. @param block A block which will be invoked in background queue when finished.
  138. */
  139. - (void)removeAllObjectsWithBlock:(void(^)(void))block;
  140. /**
  141. Empties the cache with block.
  142. This method returns immediately and executes the clear operation with block in background.
  143. @warning You should not send message to this instance in these blocks.
  144. @param progress This block will be invoked during removing, pass nil to ignore.
  145. @param end This block will be invoked at the end, pass nil to ignore.
  146. */
  147. - (void)removeAllObjectsWithProgressBlock:(nullable void(^)(int removedCount, int totalCount))progress
  148. endBlock:(nullable void(^)(BOOL error))end;
  149. @end
  150. NS_ASSUME_NONNULL_END