[ { "path": ".gitignore", "content": "# Mac OS X Finder\n.DS_Store\n\n# Xcode\nbuild/*\n*.pbxuser\n!default.pbxuser\n*.mode1v3\n!default.mode1v3\n*.mode2v3\n!default.mode2v3\n*.perspectivev3\n!default.perspectivev3\n*.xcworkspace\n!default.xcworkspace\nxcuserdata\nprofile\n*.moved-aside\nDerivedData\n\n# Demo Images\nFastImageCache/FastImageCacheDemo/Demo Images/*.jpg\nCarthage\n" }, { "path": "FastImageCache/FastImageCache/FastImageCache/FICEntity.h", "content": "//\n// FICEntity.h\n// FastImageCache\n//\n// Copyright (c) 2013 Path, Inc.\n// See LICENSE for full license agreement.\n//\n\n#import \"FICImports.h\"\n@class FICImageFormat;\n\nNS_ASSUME_NONNULL_BEGIN\n\ntypedef void (^FICEntityImageDrawingBlock)(CGContextRef context, CGSize contextSize);\n\n/**\n `FICEntity` is a protocol that classes interacting with the image cache must conform to. An entity uniquely identifies entries in image tables, which are instances of ``.\n */\n@protocol FICEntity \n\n@required\n\n/**\n A string that uniquely identifies this entity.\n \n @discussion Within each image table, each entry is identified by an entity's UUID. Ideally, this value should never change for an entity. For example, if your entity class is a person\n model, its UUID might be an API-assigned, unchanging, unique user ID. No matter how the properties of the person change, its user ID should never change.\n */\n@property (nonatomic, copy, readonly) NSString *fic_UUID;\n\n/**\n A string that uniquely identifies an entity's source image.\n \n @discussion While `` should be unchanging, a source image UUID might change. For example, if your entity class is a person model, its source image UUID might change every time the\n person changes their profile photo. In this case, the source image UUID might be a hash of the profile photo URL (assuming each image is given a unique URL).\n */\n@property (nonatomic, copy, readonly) NSString *fic_sourceImageUUID;\n\n/**\n Returns the source image URL associated with a specific format name.\n \n @param formatName The name of the image format that identifies which image table is requesting the source image.\n \n @return A URL representing the requested source image.\n \n @discussion Fast Image Cache operates on URLs when requesting source images. Typically, these URLs will point to remote image resources that must be downloaded from the Internet. While the\n URL returned by this method must be a valid instance of `NSURL`, it does not need to point to an actual remote resource. The URL might point to a file path on disk or be composed of a custom\n URL scheme of your choosing. The image cache's delegate is prompted to provide a source image for a particular entity and format name when it cannot find the requested image. It only uses the\n URL returned by this method to key image cache requests. No network or file operations are performed by the image cache.\n \n An example of when this method might return different source image URLs for the same entity is if you have defined several image formats for different thumbnail sizes and styles. For very\n large thumbnails, the source image URL might be the original image. For smaller thumbnails, the source image URL might point to a downscaled version of the original image.\n \n @see FICImageFormat\n @see [FICImageCacheDelegate imageCache:wantsSourceImageForEntity:withFormatName:completionBlock:]\n */\n- (nullable NSURL *)fic_sourceImageURLWithFormatName:(NSString *)formatName;\n\n\n/**\n Returns the drawing block for a specific image and format name.\n \n @param image The cached image that represents this entity.\n \n @param formatName The name of the image format that identifies which image table is requesting the source image.\n \n @return The drawing block used to draw the image data to be stored in the image table.\n \n The drawing block's type is defined as follows:\n \n typedef void (^FICEntityImageDrawingBlock)(CGContextRef context, CGSize contextSize)\n \n @discussion Each entity is responsible for drawing its own source image into the bitmap context provided by the image table that will store the image data. Often it is sufficient to simply\n draw the image into the bitmap context. However, if you wish to apply any additional graphics processing to the source image before it is stored (such as clipping the image to a roundect rect),\n you may use this block to do so.\n \n @note This block will always be called from the serial dispatch queue used by the image cache.\n */\n- (nullable FICEntityImageDrawingBlock)fic_drawingBlockForImage:(UIImage *)image withFormatName:(NSString *)formatName;\n\n@optional\n/**\n Returns the image for a format\n \n @param format The image format that identifies which image table is requesting the source image.\n */\n- (nullable UIImage *)fic_imageForFormat:(FICImageFormat *)format;\n\n@end\n\nNS_ASSUME_NONNULL_END" }, { "path": "FastImageCache/FastImageCache/FastImageCache/FICImageCache+FICErrorLogging.h", "content": "//\n// FICImageCache+FICErrorLogging.h\n// FastImageCache\n//\n// Copyright (c) 2013 Path, Inc.\n// See LICENSE for full license agreement.\n//\n\n#import \"FICImageCache.h\"\n\n/**\n This category on `` simply exposes its private logging mechanism to other classes.\n */\n@interface FICImageCache (FICErrorLogging)\n\n///-----------------------------\n/// @name Logging Error Messages\n///-----------------------------\n\n/**\n Passes an error message to the image cache.\n \n @param message A string representing the error message.\n \n @discussion Rather than logging directly to standard output, Fast Image Cache classes pass all error logging to the shared `` instance. `` then allows its delegate to handle the\n message.\n \n @see [FICImageCacheDelegate imageCache:errorDidOccurWithMessage:]\n */\n- (void)_logMessage:(NSString *)message;\n\n@end\n" }, { "path": "FastImageCache/FastImageCache/FastImageCache/FICImageCache.h", "content": "//\n// FICImageCache.h\n// FastImageCache\n//\n// Copyright (c) 2013 Path, Inc.\n// See LICENSE for full license agreement.\n//\n\n#import \"FICImports.h\"\n#import \"FICImageFormat.h\"\n#import \"FICEntity.h\"\n\n@protocol FICEntity;\n@protocol FICImageCacheDelegate;\n\ntypedef void (^FICImageCacheCompletionBlock)(id _Nullable entity, NSString * _Nonnull formatName, UIImage * _Nullable image);\ntypedef void (^FICImageRequestCompletionBlock)(UIImage * _Nullable sourceImage);\n\nNS_ASSUME_NONNULL_BEGIN\n\n/**\n `FICImageCache` is the primary class for managing and interacting with the image cache. Applications using the image cache create one or more ``\n objects. These formats effectively act as logical groupings for image data stored in the image cache. An `` object is created for each format defined by\n your application to allow for efficient storage and retrieval of image data. Image data is keyed off of objects conforming to the `` protocol as well as an\n image format name.\n */\n@interface FICImageCache : NSObject\n\n/**\n The namespace of the image cache.\n \n @discussion Namespace is responsible for isolation of dirrerent image cache instances on file system level. Namespace should be unique across application.\n */\n\n@property (readonly, nonatomic) NSString *nameSpace;\n\n///----------------------------\n/// @name Managing the Delegate\n///----------------------------\n\n/**\n The delegate of the image cache.\n \n @discussion The delegate is responsible for asynchronously providing the source image for an entity. Optionally, the delegate can require that all formats in a format\n family for a particular entity be processed. Any errors that occur in the image cache are also communicated back to the delegate.\n */\n@property (nonatomic, weak) id delegate;\n\n///---------------------------------------\n/// @name Creating Image Cache instances\n///---------------------------------------\n\n/**\n Returns new image cache.\n \n @return A new instance of `FICImageCache`.\n \n @param nameSpace The namespace that uniquely identifies current image cahce entity. If no nameSpace given, default namespace will be used.\n \n @note Fast Image Cache can either be used as a singleton for convenience or can exist as multiple instances. \n However, all instances of `FICImageCache` will make use same dispatch queue. To separate location on disk for storing image tables namespaces are used.\n \n @see [FICImageCache dispatchQueue]\n */\n\n- (instancetype)initWithNameSpace:(NSString *)nameSpace;\n\n///---------------------------------------\n/// @name Accessing the Shared Image Cache\n///---------------------------------------\n\n/**\n Returns the shared image cache.\n \n @return A shared instance of `FICImageCache`.\n \n @note Shared instance always binded to default namespace.\n \n @see [FICImageCache dispatchQueue]\n */\n+ (instancetype)sharedImageCache;\n\n/**\n Returns the shared dispatch queue used by all instances of `FICImageCache`.\n \n @return A generic, shared dispatch queue of type `dispatch_queue_t`.\n \n @note All instances of `FICImageCache` make use a single, shared dispatch queue to do their work.\n */\n+ (dispatch_queue_t)dispatchQueue;\n\n///---------------------------------\n/// @name Working with Image Formats\n///---------------------------------\n\n/**\n Sets the image formats to be used by the image cache.\n \n @param formats An array of `` objects.\n \n @note Once the image formats have been set, subsequent calls to this method will do nothing.\n */\n- (void)setFormats:(NSArray *)formats;\n\n/**\n Returns an image format previously associated with the image cache.\n \n @param formatName The name of the image format to return.\n \n @return An image format with the name `formatName` or `nil` if no format with that name exists.\n */\n- (nullable FICImageFormat *)formatWithName:(NSString *)formatName;\n\n/**\n Returns all the image formats of the same family previously associated with the image cache.\n \n @param family The name of the family of image formats to return.\n \n @return An array of `` objects whose family is `family` or `nil` if no format belongs to that family.\n */\n- (nullable NSArray *)formatsWithFamily:(NSString *)family;\n\n///-----------------------------------------------\n/// @name Storing, Retrieving, and Deleting Images\n///-----------------------------------------------\n\n/**\n Manually sets the the image to be used by the image cache for a particular entity and format name.\n \n @discussion Usually the image cache's delegate is responsible for lazily providing the source image for a given entity. This source image is then processed according\n to the drawing block defined by an entity for a given image format. This method allows the sender to explicitly set the image data to be stored in the image cache.\n After the image has been processed by the image cache, the completion block is called asynchronously on the main queue.\n \n @param image The image to store in the image cache.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image.\n \n @param completionBlock The completion block that is called after the image has been processed or if an error occurs.\n \n The completion block's type is defined as follows:\n \n typedef void (^FICImageCacheCompletionBlock)(id entity, NSString *formatName, UIImage *image)\n */\n- (void)setImage:(UIImage *)image forEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(nullable FICImageCacheCompletionBlock)completionBlock;\n\n/**\n Attempts to synchronously retrieve an image from the image cache.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image. Must not be nil.\n \n @param completionBlock The completion block that is called when the requested image is available or if an error occurs.\n \n The completion block's type is defined as follows:\n \n typedef void (^FICImageCacheCompletionBlock)(id entity, NSString *formatName, UIImage *image)\n \n If the requested image already exists in the image cache, then the completion block is immediately called synchronously on the current thread. If the requested image\n does not already exist in the image cache, then the completion block will be called asynchronously on the main thread as soon as the requested image is available.\n \n @return `YES` if the requested image already exists in the image case, `NO` if the image needs to be provided to the image cache by its delegate.\n \n @discussion Even if you make a synchronous image retrieval request, if the image does not yet exist in the image cache, the delegate will be asked to provide a source\n image, and it will be processed. This always occurs asynchronously. In this case, the return value from this method will be `NO`, and the image will be available in the\n completion block.\n \n @note You can always rely on the completion block being called. If an error occurs for any reason, the `image` parameter of the completion block will be `nil`. See\n <[FICImageCacheDelegate imageCache:errorDidOccurWithMessage:]> for information about being notified when errors occur.\n */\n- (BOOL)retrieveImageForEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(nullable FICImageCacheCompletionBlock)completionBlock;\n\n/**\n Asynchronously retrieves an image from the image cache.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image. Must not be nil.\n \n @param completionBlock The completion block that is called when the requested image is available or if an error occurs.\n \n The completion block's type is defined as follows:\n \n typedef void (^FICImageCacheCompletionBlock)(id entity, NSString *formatName, UIImage *image)\n \n Unlike its synchronous counterpart, this method will always call its completion block asynchronously on the main thread, even if the request image is already in the\n image cache.\n \n @return `YES` if the requested image already exists in the image case, `NO` if the image needs to be provided to the image cache by its delegate.\n \n @note You can always rely on the completion block being called. If an error occurs for any reason, the `image` parameter of the completion block will be `nil`. See\n <[FICImageCacheDelegate imageCache:errorDidOccurWithMessage:]> for information about being notified when errors occur.\n \n @see [FICImageCache retrieveImageForEntity:withFormatName:completionBlock:]\n */\n- (BOOL)asynchronouslyRetrieveImageForEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(nullable FICImageCacheCompletionBlock)completionBlock;\n\n/**\n Deletes an image from the image cache.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image.\n */\n- (void)deleteImageForEntity:(id )entity withFormatName:(NSString *)formatName;\n\n///-------------------------------\n/// @name Canceling Image Requests\n///-------------------------------\n\n/**\n Cancels an active request for an image from the image cache.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image.\n \n @discussion After this method is called, the completion block of the <[FICImageCacheDelegate imageCache:wantsSourceImageForEntity:withFormatName:completionBlock:]> delegate\n method for the corresponding entity, if called, does nothing.\n */\n- (void)cancelImageRetrievalForEntity:(id )entity withFormatName:(NSString *)formatName;\n \n///-----------------------------------\n/// @name Checking for Image Existence\n///-----------------------------------\n\n/**\n Returns whether or not an image exists in the image cache.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image.\n \n @return `YES` if an image exists in the image cache for a given entity and format name. Otherwise, `NO`.\n */\n- (BOOL)imageExistsForEntity:(id )entity withFormatName:(NSString *)formatName;\n\n///--------------------------------\n/// @name Resetting the Image Cache\n///--------------------------------\n\n/**\n Resets the image cache by deleting all image tables and their contents.\n \n @note Resetting an image cache does not reset its image formats.\n */\n- (void)reset;\n\n@end\n\n/**\n `FICImageCacheDelegate` defines the required and optional actions that an image cache's delegate can perform.\n */\n@protocol FICImageCacheDelegate \n\n@optional\n\n/**\n This method is called on the delegate when the image cache needs a source image.\n \n @param imageCache The image cache that is requesting the source image.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image.\n \n @param completionBlock The completion block that the receiver must call when it has a source image ready.\n \n The completion block's type is defined as follows:\n \n typedef void (^FICImageRequestCompletionBlock)(UIImage *sourceImage)\n \n The completion block must always be called on the main thread.\n \n @discussion A source image is usually the original, full-size image that represents an entity. This source image is processed for every unique format to create the\n actual image data to be stored in the image cache. This method is an asynchronous data provider, so nothing is actually returned to the sender. Instead, the delegate's\n implementation is expected to call the completion block once an image is available.\n \n Fast Image Cache is architected under the typical design pattern whereby model objects provide a URL to certain image assets and allow the client to actually retrieve\n the images via network requests only when needed. As a result, the implementation of this method will usually involve creating an asynchronous network request using\n the URL returned by <[FICEntity sourceImageURLWithFormatName:]>, deserializing the image data when the request completes, and finally calling this method's completion\n block to provide the image cache with the source image.\n */\n- (void)imageCache:(FICImageCache *)imageCache wantsSourceImageForEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(nullable FICImageRequestCompletionBlock)completionBlock;\n\n/**\n This method is called on the delegate when the image cache has received an image retrieval cancellation request.\n \n @param imageCache The image cache that has received the image retrieval cancellation request.\n \n @param entity The entity that uniquely identifies the source image.\n \n @param formatName The format name that uniquely identifies which image table to look in for the cached image.\n \n @discussion When an image retrieval cancellation request is made to the image cache, it removes all of its internal bookkeeping for requests. However, it is still the\n delegate's responsibility to cancel whatever logic is it performing to provide a source image to the cache (e.g., a network request).\n \n @see [FICImageCache cancelImageRetrievalForEntity:withFormatName:]\n */\n- (void)imageCache:(FICImageCache *)imageCache cancelImageLoadingForEntity:(id )entity withFormatName:(NSString *)formatName;\n\n/**\n This method is called on the delegate to determine whether or not all formats in a family should be processed right now.\n \n @note If this method is not implemented by the delegate, the default value is `YES`.\n \n @param imageCache The image cache that is requesting the source image.\n \n @param formatFamily The name of a format family.\n \n @param entity The entity that uniquely identifies the source image.\n \n @return `YES` if all formats in a format family should be processed. Otherwise, `NO`.\n \n @discussion This method is called whenever new image data is stored in the image cache. Because format families are used to group multiple different formats together,\n typically the delegate will want to return `YES` here so that other formats in the same family can be processed.\n \n For example, if your image cache has defined several different thumbnail sizes and styles for a person model, and if a person changes their profile photo, you would\n want every thumbnail size and style is updated with the new source image.\n */\n- (BOOL)imageCache:(FICImageCache *)imageCache shouldProcessAllFormatsInFamily:(NSString *)formatFamily forEntity:(id )entity;\n\n/**\n This method is called on the delegate whenever the image cache has an error message to log.\n \n @param imageCache The image cache that is requesting the source image.\n \n @param errorMessage The error message generated by the image cache.\n \n @discussion Fast Image Cache will not explicitly log any messages to standard output. Instead, it allows the delegate to handle (or ignore) any error output.\n */\n- (void)imageCache:(FICImageCache *)imageCache errorDidOccurWithMessage:(NSString *)errorMessage;\n\n@end\n\nNS_ASSUME_NONNULL_END" }, { "path": "FastImageCache/FastImageCache/FastImageCache/FICImageCache.m", "content": "//\n// FICImageCache.m\n// FastImageCache\n//\n// Copyright (c) 2013 Path, Inc.\n// See LICENSE for full license agreement.\n//\n\n#import \"FICImageCache.h\"\n#import \"FICEntity.h\"\n#import \"FICImageTable.h\"\n#import \"FICImageFormat.h\"\n\n#pragma mark Internal Definitions\n\nstatic void _FICAddCompletionBlockForEntity(NSString *formatName, NSMutableDictionary *entityRequestsDictionary, id entity, FICImageCacheCompletionBlock completionBlock);\n\nstatic NSString *const FICImageCacheFormatKey = @\"FICImageCacheFormatKey\";\nstatic NSString *const FICImageCacheCompletionBlocksKey = @\"FICImageCacheCompletionBlocksKey\";\nstatic NSString *const FICImageCacheEntityKey = @\"FICImageCacheEntityKey\";\n\n#pragma mark - Class Extension\n\n@interface FICImageCache () {\n NSMutableDictionary *_formats;\n NSMutableDictionary *_imageTables;\n NSMutableDictionary *_requests;\n \n BOOL _delegateImplementsWantsSourceImageForEntityWithFormatNameCompletionBlock;\n BOOL _delegateImplementsShouldProcessAllFormatsInFamilyForEntity;\n BOOL _delegateImplementsErrorDidOccurWithMessage;\n BOOL _delegateImplementsCancelImageLoadingForEntityWithFormatName;\n}\n\n@end\n\n#pragma mark\n\n@implementation FICImageCache\n\n@synthesize delegate = _delegate;\n\n#pragma mark - Property Accessors\n\n- (void)setDelegate:(id)delegate {\n if (delegate != _delegate) {\n _delegate = delegate;\n \n _delegateImplementsWantsSourceImageForEntityWithFormatNameCompletionBlock = [_delegate respondsToSelector:@selector(imageCache:wantsSourceImageForEntity:withFormatName:completionBlock:)];\n _delegateImplementsShouldProcessAllFormatsInFamilyForEntity = [_delegate respondsToSelector:@selector(imageCache:shouldProcessAllFormatsInFamily:forEntity:)];\n _delegateImplementsErrorDidOccurWithMessage = [_delegate respondsToSelector:@selector(imageCache:errorDidOccurWithMessage:)];\n _delegateImplementsCancelImageLoadingForEntityWithFormatName = [_delegate respondsToSelector:@selector(imageCache:cancelImageLoadingForEntity:withFormatName:)];\n }\n}\n\n#pragma mark - Object Lifecycle\n\n+ (instancetype)sharedImageCache {\n static dispatch_once_t onceToken;\n static FICImageCache *__imageCache = nil;\n dispatch_once(&onceToken, ^{\n __imageCache = [[[self class] alloc] init];\n });\n\n return __imageCache;\n}\n\n+ (dispatch_queue_t)dispatchQueue {\n static dispatch_queue_t __imageCacheDispatchQueue = NULL;\n static dispatch_once_t onceToken;\n dispatch_once(&onceToken, ^{\n __imageCacheDispatchQueue = dispatch_queue_create(\"com.path.FastImageCacheQueue\", NULL);\n });\n return __imageCacheDispatchQueue;\n}\n\n- (instancetype)init {\n return [self initWithNameSpace:@\"FICDefaultNamespace\"];\n}\n\n- (instancetype)initWithNameSpace:(NSString *)nameSpace {\n self = [super init];\n if (self) {\n _formats = [[NSMutableDictionary alloc] init];\n _imageTables = [[NSMutableDictionary alloc] init];\n _requests = [[NSMutableDictionary alloc] init];\n _nameSpace = nameSpace;\n }\n return self;\n}\n\n#pragma mark - Working with Formats\n\n- (void)setFormats:(NSArray *)formats {\n if ([_formats count] > 0) {\n [self _logMessage:[NSString stringWithFormat:@\"*** FIC Error: %s FICImageCache has already been configured with its image formats.\", __PRETTY_FUNCTION__]];\n } else {\n NSMutableSet *imageTableFiles = [NSMutableSet set];\n FICImageFormatDevices currentDevice = [[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad ? FICImageFormatDevicePad : FICImageFormatDevicePhone;\n for (FICImageFormat *imageFormat in formats) {\n NSString *formatName = [imageFormat name];\n FICImageFormatDevices devices = [imageFormat devices];\n if (devices & currentDevice) {\n // Only initialize an image table for this format if it is needed on the current device.\n FICImageTable *imageTable = [[FICImageTable alloc] initWithFormat:imageFormat imageCache:self];\n [_imageTables setObject:imageTable forKey:formatName];\n [_formats setObject:imageFormat forKey:formatName];\n \n [imageTableFiles addObject:[[imageTable tableFilePath] lastPathComponent]];\n [imageTableFiles addObject:[[imageTable metadataFilePath] lastPathComponent]];\n }\n }\n \n // Remove any extraneous files in the image tables directory\n NSFileManager *fileManager = [NSFileManager defaultManager];\n NSString *directoryPath = [FICImageTable directoryPath];\n if (self.nameSpace) {\n directoryPath = [directoryPath stringByAppendingPathComponent:self.nameSpace];\n }\n NSArray *fileNames = [fileManager contentsOfDirectoryAtPath:directoryPath error:nil];\n for (NSString *fileName in fileNames) {\n if ([imageTableFiles containsObject:fileName] == NO) {\n // This is an extraneous file, which is no longer needed.\n NSString* filePath = [directoryPath stringByAppendingPathComponent:fileName];\n [fileManager removeItemAtPath:filePath error:nil];\n }\n }\n }\n}\n\n- (FICImageFormat *)formatWithName:(NSString *)formatName {\n return [_formats objectForKey:formatName];\n}\n\n- (NSArray *)formatsWithFamily:(NSString *)family {\n NSMutableArray *formats = nil;\n for (FICImageFormat *format in [_formats allValues]) {\n if ([[format family] isEqualToString:family]) {\n if (formats == nil) {\n formats = [NSMutableArray array];\n }\n \n [formats addObject:format];\n }\n }\n \n return [formats copy];\n}\n\n#pragma mark - Retrieving Images\n\n- (BOOL)retrieveImageForEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(FICImageCacheCompletionBlock)completionBlock {\n return [self _retrieveImageForEntity:entity withFormatName:formatName loadSynchronously:YES completionBlock:completionBlock];\n}\n\n- (BOOL)asynchronouslyRetrieveImageForEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(FICImageCacheCompletionBlock)completionBlock {\n return [self _retrieveImageForEntity:entity withFormatName:formatName loadSynchronously:NO completionBlock:completionBlock];\n}\n\n- (BOOL)_retrieveImageForEntity:(id )entity withFormatName:(NSString *)formatName loadSynchronously:(BOOL)loadSynchronously completionBlock:(FICImageCacheCompletionBlock)completionBlock {\n NSParameterAssert(formatName);\n\t\n BOOL imageExists = NO;\n \n FICImageTable *imageTable = [_imageTables objectForKey:formatName];\n NSString *entityUUID = [entity fic_UUID];\n NSString *sourceImageUUID = [entity fic_sourceImageUUID];\n \n if (loadSynchronously == NO && [imageTable entryExistsForEntityUUID:entityUUID sourceImageUUID:sourceImageUUID]) {\n imageExists = YES;\n \n dispatch_async([FICImageCache dispatchQueue], ^{\n UIImage *image = [imageTable newImageForEntityUUID:entityUUID sourceImageUUID:sourceImageUUID preheatData:YES];\n \n if (completionBlock != nil) {\n dispatch_async(dispatch_get_main_queue(), ^{\n completionBlock(entity, formatName, image);\n });\n }\n });\n } else {\n UIImage *image = [imageTable newImageForEntityUUID:entityUUID sourceImageUUID:sourceImageUUID preheatData:NO];\n imageExists = image != nil;\n \n dispatch_block_t completionBlockCallingBlock = ^{\n if (completionBlock != nil) {\n if (loadSynchronously) {\n completionBlock(entity, formatName, image);\n } else {\n dispatch_async(dispatch_get_main_queue(), ^{\n completionBlock(entity, formatName, image);\n });\n }\n }\n };\n \n if (image == nil) {\n // No image for this UUID exists in the image table. We'll need to ask the delegate to retrieve the source asset.\n NSURL *sourceImageURL = [entity fic_sourceImageURLWithFormatName:formatName];\n \n if (sourceImageURL != nil) {\n // We check to see if this image is already being fetched.\n BOOL needsToFetch = NO;\n @synchronized (_requests) {\n NSMutableDictionary *requestDictionary = [_requests objectForKey:sourceImageURL];\n if (requestDictionary == nil) {\n // If we're here, then we aren't currently fetching this image.\n requestDictionary = [NSMutableDictionary dictionary];\n [_requests setObject:requestDictionary forKey:sourceImageURL];\n needsToFetch = YES;\n }\n \n _FICAddCompletionBlockForEntity(formatName, requestDictionary, entity, completionBlock);\n }\n\n if (needsToFetch) {\n @autoreleasepool {\n UIImage *image;\n if ([entity respondsToSelector:@selector(fic_imageForFormat:)]){\n FICImageFormat *format = [self formatWithName:formatName];\n image = [entity fic_imageForFormat:format];\n }\n \n if (image){\n [self _imageDidLoad:image forURL:sourceImageURL];\n } else if (_delegateImplementsWantsSourceImageForEntityWithFormatNameCompletionBlock){\n [_delegate imageCache:self wantsSourceImageForEntity:entity withFormatName:formatName completionBlock:^(UIImage *sourceImage) {\n [self _imageDidLoad:sourceImage forURL:sourceImageURL];\n }];\n }\n }\n }\n } else {\n NSString *message = [NSString stringWithFormat:@\"*** FIC Error: %s entity %@ returned a nil source image URL for image format %@.\", __PRETTY_FUNCTION__, entity, formatName];\n [self _logMessage:message];\n \n completionBlockCallingBlock();\n }\n } else {\n completionBlockCallingBlock();\n }\n }\n \n return imageExists;\n}\n\n- (void)_imageDidLoad:(UIImage *)image forURL:(NSURL *)URL {\n NSDictionary *requestDictionary;\n @synchronized (_requests) {\n requestDictionary = [_requests objectForKey:URL];\n [_requests removeObjectForKey:URL];\n // Now safe to use requestsDictionary outside the lock, because we've taken ownership from _requests\n }\n\n if (requestDictionary != nil) {\n for (NSMutableDictionary *entityDictionary in [requestDictionary allValues]) {\n id entity = [entityDictionary objectForKey:FICImageCacheEntityKey];\n NSString *formatName = [entityDictionary objectForKey:FICImageCacheFormatKey];\n NSDictionary *completionBlocksDictionary = [entityDictionary objectForKey:FICImageCacheCompletionBlocksKey];\n if (image != nil){\n [self _processImage:image forEntity:entity completionBlocksDictionary:completionBlocksDictionary];\n } else {\n NSArray *completionBlocks = [completionBlocksDictionary objectForKey:formatName];\n if (completionBlocks != nil) {\n dispatch_async(dispatch_get_main_queue(), ^{\n for (FICImageCacheCompletionBlock completionBlock in completionBlocks) {\n completionBlock(entity, formatName, nil);\n }\n });\n }\n }\n }\n }\n}\n\nstatic void _FICAddCompletionBlockForEntity(NSString *formatName, NSMutableDictionary *entityRequestsDictionary, id entity, FICImageCacheCompletionBlock completionBlock) {\n NSString *entityUUID = [entity fic_UUID];\n NSMutableDictionary *requestDictionary = [entityRequestsDictionary objectForKey:entityUUID];\n NSMutableDictionary *completionBlocks = nil;\n \n if (requestDictionary == nil) {\n // This is the first time we're dealing with this particular entity for this URL request.\n requestDictionary = [NSMutableDictionary dictionaryWithObjectsAndKeys:entity, FICImageCacheEntityKey, nil];\n [entityRequestsDictionary setObject:requestDictionary forKey:entityUUID];\n [requestDictionary setObject:formatName forKey:FICImageCacheFormatKey];\n \n // Dictionary where keys are imageFormats, and each value is an array of the completion blocks for the requests for this\n // URL at the specified format.\n completionBlocks = [NSMutableDictionary dictionary];\n [requestDictionary setObject:completionBlocks forKey:FICImageCacheCompletionBlocksKey];\n } else {\n // We already have a request dictionary for this entity, so we just need to append a completion block.\n completionBlocks = [requestDictionary objectForKey:FICImageCacheCompletionBlocksKey];\n }\n \n if (completionBlock != nil) {\n NSMutableArray *blocksArray = [completionBlocks objectForKey:formatName];\n if (blocksArray == nil) {\n blocksArray = [NSMutableArray array];\n [completionBlocks setObject:blocksArray forKey:formatName];\n }\n \n FICImageCacheCompletionBlock completionBlockCopy = [completionBlock copy];\n [blocksArray addObject:completionBlockCopy];\n }\n}\n\n#pragma mark - Storing Images\n\n- (void)setImage:(UIImage *)image forEntity:(id )entity withFormatName:(NSString *)formatName completionBlock:(FICImageCacheCompletionBlock)completionBlock {\n if (image != nil && entity != nil) {\n NSDictionary *completionBlocksDictionary = nil;\n \n if (completionBlock != nil) {\n completionBlocksDictionary = [NSDictionary dictionaryWithObject:[NSArray arrayWithObject:[completionBlock copy]] forKey:formatName];\n }\n \n NSString *entityUUID = [entity fic_UUID];\n FICImageTable *imageTable = [_imageTables objectForKey:formatName];\n if (imageTable) {\n [imageTable deleteEntryForEntityUUID:entityUUID];\n \n [self _processImage:image forEntity:entity completionBlocksDictionary:completionBlocksDictionary];\n } else {\n [self _logMessage:[NSString stringWithFormat:@\"*** FIC Error: %s Couldn't find image table with format name %@\", __PRETTY_FUNCTION__, formatName]];\n }\n }\n}\n\n- (void)_processImage:(UIImage *)image forEntity:(id )entity completionBlocksDictionary:(NSDictionary *)completionBlocksDictionary {\n for (NSString *formatToProcess in [self formatsToProcessForCompletionBlocks:completionBlocksDictionary\n entity:entity]) {\n FICImageTable *imageTable = [_imageTables objectForKey:formatToProcess];\n NSArray *completionBlocks = [completionBlocksDictionary objectForKey:formatToProcess];\n [self _processImage:image forEntity:entity imageTable:imageTable completionBlocks:completionBlocks];\n }\n}\n\n- (void)_processImage:(UIImage *)image forEntity:(id )entity imageTable:(FICImageTable *)imageTable completionBlocks:(NSArray *)completionBlocks {\n if (imageTable != nil) {\n if ([entity fic_UUID] == nil) {\n [self _logMessage:[NSString stringWithFormat:@\"*** FIC Error: %s entity %@ is missing its UUID.\", __PRETTY_FUNCTION__, entity]];\n return;\n }\n \n if ([entity fic_sourceImageUUID] == nil) {\n [self _logMessage:[NSString stringWithFormat:@\"*** FIC Error: %s entity %@ is missing its source image UUID.\", __PRETTY_FUNCTION__, entity]];\n return;\n }\n \n NSString *entityUUID = [entity fic_UUID];\n NSString *sourceImageUUID = [entity fic_sourceImageUUID];\n FICImageFormat *imageFormat = [imageTable imageFormat];\n NSString *imageFormatName = [imageFormat name];\n FICEntityImageDrawingBlock imageDrawingBlock = [entity fic_drawingBlockForImage:image withFormatName:imageFormatName];\n \n dispatch_async([FICImageCache dispatchQueue], ^{\n [imageTable setEntryForEntityUUID:entityUUID sourceImageUUID:sourceImageUUID imageDrawingBlock:imageDrawingBlock];\n\n UIImage *resultImage = [imageTable newImageForEntityUUID:entityUUID sourceImageUUID:sourceImageUUID preheatData:NO];\n \n if (completionBlocks != nil) {\n dispatch_async(dispatch_get_main_queue(), ^{\n NSString *formatName = [[imageTable imageFormat] name];\n for (FICImageCacheCompletionBlock completionBlock in completionBlocks) {\n completionBlock(entity, formatName, resultImage);\n }\n });\n }\n });\n }\n}\n\n- (NSSet *)formatsToProcessForCompletionBlocks:(NSDictionary *)completionBlocksDictionary entity:(id )entity {\n // At the very least, we must process all formats with pending completion blocks\n NSMutableSet *formatsToProcess = [NSMutableSet setWithArray:completionBlocksDictionary.allKeys];\n\n // Get the list of format families included by the formats we have to process\n NSMutableSet *families;\n for (NSString *formatToProcess in formatsToProcess) {\n FICImageTable *imageTable = _imageTables[formatToProcess];\n FICImageFormat *imageFormat = imageTable.imageFormat;\n NSString *tableFormatFamily = imageFormat.family;\n if (tableFormatFamily) {\n if (!families) {\n families = [NSMutableSet set];\n }\n [families addObject:tableFormatFamily];\n }\n }\n\n // The delegate can override the list of families to process\n if (_delegateImplementsShouldProcessAllFormatsInFamilyForEntity) {\n [families minusSet:[families objectsPassingTest:^BOOL(NSString *familyName, BOOL *stop) {\n return ![_delegate imageCache:self shouldProcessAllFormatsInFamily:familyName forEntity:entity];\n }]];\n }\n\n // Ensure that all formats from all of those families are included in the list\n if (families.count) {\n for (FICImageTable *table in _imageTables.allValues) {\n FICImageFormat *imageFormat = table.imageFormat;\n NSString *imageFormatName = imageFormat.name;\n // If we're already processing this format, keep looking\n if ([formatsToProcess containsObject:imageFormatName]) {\n continue;\n }\n\n // If this format isn't included in any referenced family, keep looking\n if (![families containsObject:imageFormat.family]) {\n continue;\n }\n\n // If the image already exists, keep going\n if ([table entryExistsForEntityUUID:entity.fic_UUID sourceImageUUID:entity.fic_sourceImageUUID]) {\n continue;\n }\n\n [formatsToProcess addObject:imageFormatName];\n }\n }\n\n return formatsToProcess;\n}\n\n#pragma mark - Checking for Image Existence\n\n- (BOOL)imageExistsForEntity:(id )entity withFormatName:(NSString *)formatName {\n FICImageTable *imageTable = [_imageTables objectForKey:formatName];\n NSString *entityUUID = [entity fic_UUID];\n NSString *sourceImageUUID = [entity fic_sourceImageUUID];\n \n BOOL imageExists = [imageTable entryExistsForEntityUUID:entityUUID sourceImageUUID:sourceImageUUID];\n\n return imageExists;\n}\n\n#pragma mark - Invalidating Image Data\n\n- (void)deleteImageForEntity:(id )entity withFormatName:(NSString *)formatName {\n FICImageTable *imageTable = [_imageTables objectForKey:formatName];\n NSString *entityUUID = [entity fic_UUID];\n [imageTable deleteEntryForEntityUUID:entityUUID];\n}\n\n- (void)cancelImageRetrievalForEntity:(id )entity withFormatName:(NSString *)formatName {\n NSURL *sourceImageURL = [entity fic_sourceImageURLWithFormatName:formatName];\n NSString *entityUUID = [entity fic_UUID];\n\n BOOL cancelImageLoadingForEntity = NO;\n @synchronized (_requests) {\n NSMutableDictionary *requestDictionary = [_requests objectForKey:sourceImageURL];\n if (requestDictionary) {\n NSMutableDictionary *entityRequestsDictionary = [requestDictionary objectForKey:entityUUID];\n if (entityRequestsDictionary) {\n NSMutableDictionary *completionBlocksDictionary = [entityRequestsDictionary objectForKey:FICImageCacheCompletionBlocksKey];\n [completionBlocksDictionary removeObjectForKey:formatName];\n\n if ([completionBlocksDictionary count] == 0) {\n [requestDictionary removeObjectForKey:entityUUID];\n }\n\n if ([requestDictionary count] == 0) {\n [_requests removeObjectForKey:sourceImageURL];\n cancelImageLoadingForEntity = YES;\n }\n }\n }\n }\n\n if (cancelImageLoadingForEntity && _delegateImplementsCancelImageLoadingForEntityWithFormatName) {\n [_delegate imageCache:self cancelImageLoadingForEntity:entity withFormatName:formatName];\n }\n}\n\n- (void)reset {\n for (FICImageTable *imageTable in [_imageTables allValues]) {\n dispatch_async([[self class] dispatchQueue], ^{\n [imageTable reset];\n });\n }\n}\n\n#pragma mark - Logging Errors\n\n- (void)_logMessage:(NSString *)message {\n if (_delegateImplementsErrorDidOccurWithMessage) {\n [_delegate imageCache:self errorDidOccurWithMessage:message];\n }\n}\n\n@end\n" }, { "path": "FastImageCache/FastImageCache/FastImageCache/FICImageFormat.h", "content": "//\n// FICImageFormat.h\n// FastImageCache\n//\n// Copyright (c) 2013 Path, Inc.\n// See LICENSE for full license agreement.\n//\n\n#import \"FICImports.h\"\n\n@class FICImageTable;\n\ntypedef NS_OPTIONS(NSUInteger, FICImageFormatDevices) {\n FICImageFormatDevicePhone = 1 << UIUserInterfaceIdiomPhone,\n FICImageFormatDevicePad = 1 << UIUserInterfaceIdiomPad,\n};\n\ntypedef NS_ENUM(NSUInteger, FICImageFormatStyle) {\n FICImageFormatStyle32BitBGRA,\n FICImageFormatStyle32BitBGR,\n FICImageFormatStyle16BitBGR,\n FICImageFormatStyle8BitGrayscale,\n};\n\ntypedef NS_ENUM(NSUInteger, FICImageFormatProtectionMode) {\n FICImageFormatProtectionModeNone,\n FICImageFormatProtectionModeComplete,\n FICImageFormatProtectionModeCompleteUntilFirstUserAuthentication,\n};\n\n/**\n `FICImageFormat` acts as a definition for the types of images that are stored in the image cache. Each image format must have a unique name, but multiple formats can belong to the same family.\n All images associated with a particular format must have the same image dimentions and opacity preference. You can define the maximum number of entries that an image format can accommodate to\n prevent the image cache from consuming too much disk space. Each `` managed by the image cache is associated with a single image format.\n */\n\nNS_ASSUME_NONNULL_BEGIN\n@interface FICImageFormat : NSObject \n\n///------------------------------\n/// @name Image Format Properties\n///------------------------------\n\n/**\n The name of the image format. Each image format must have a unique name.\n \n @note Since multiple instances of Fast Image Cache can exist in the same application, it is important that image format name's be unique across all instances of ``. Reverse DNS naming\n is recommended (e.g., com.path.PTUserProfilePhotoLargeImageFormat).\n */\n@property (nonatomic, copy) NSString *name;\n\n/**\n The optional family that the image format belongs to. Families group together related image formats.\n \n @discussion If you are using the image cache to create several different cached variants of the same source image, all of those variants would be unique image formats that share the same family.\n \n For example, you might define a `userPhoto` family that groups together image formats with the following names: `userPhotoSmallThumbnail`, `userPhotoLargeThumbnail`, `userPhotoLargeThumbnailBorder`.\n Ideally, the same source image can be processed to create cached image data for every image format belonging to the same family.\n \n `` provides its delegate a chance to process all image formats in a given family at the same time when a particular entity-image format pair is being processed. This allows you to process\n a source image once instead of having to download and process the same source image multiple times for different formats in the same family.\n \n @see [FICImageCacheDelegate imageCache:shouldProcessAllFormatsInFamily:forEntity:]\n */\n@property (nonatomic, copy) NSString *family;\n\n/**\n The size, in points, of the images stored in the image table created by this format.\n */\n@property (nonatomic, assign) CGSize imageSize;\n\n/**\n A bitmask of type `` that defines the style of the image format.\n \n `FICImageFormatStyle` has the following values:\n \n - `FICImageFormatStyle32BitBGRA`: Full-color image format with alpha channel. 8 bits per color component, and 8 bits for the alpha channel.\n - `FICImageFormatStyle32BitBGR`: Full-color image format with no alpha channel. 8 bits per color component. The remaining 8 bits are unused.\n - `FICImageFormatStyle16BitBGR`: Reduced-color image format with no alpha channel. 5 bits per color component. The remaining bit is unused.\n - `FICImageFormatStyle8BitGrayscale`: Grayscale-only image format with no alpha channel.\n \n If you are storing images without an alpha component (e.g., JPEG images), then you should use the `FICImageFormatStyle32BitBGR` style for performance reasons. If you are storing very small images or images\n without a great deal of color complexity, the `FICImageFormatStyle16BitBGR` style may be sufficient and uses less disk space than the 32-bit styles use. For grayscale-only image formats, the\n `FICImageFormatStyle8BitGrayscale` style is sufficient and further reduces disk space usage.\n */\n@property (nonatomic, assign) FICImageFormatStyle style;\n\n/**\n The maximum number of entries that an image table can contain for this image format.\n \n @discussion Images inserted into the image table defined by this image format after the maximum number of entries has been exceeded will replace the least-recently accessed entry.\n */\n@property (nonatomic, assign) NSInteger maximumCount;\n\n/**\n A bitmask of type `` that defines which devices are managed by an image table.\n \n @discussion If the current device is not included in a particular image format, the image cache will not store image data for that device.\n */\n@property (nonatomic, assign) FICImageFormatDevices devices;\n\n/**\n The size, in pixels, of the images stored in the image table created by this format. This takes into account the screen scale.\n */\n@property (nonatomic, assign, readonly) CGSize pixelSize;\n\n/**\n The bitmap info associated with the images created with this image format.\n */\n@property (nonatomic, assign, readonly) CGBitmapInfo bitmapInfo;\n\n/**\n The number of bytes each pixel of an image created with this image format occupies.\n */\n@property (nonatomic, assign, readonly) NSInteger bytesPerPixel;\n\n/**\n The number of bits each pixel component (e.g., blue, green, red color channels) uses for images created with this image format.\n */\n@property (nonatomic, assign, readonly) NSInteger bitsPerComponent;\n\n/**\n Whether or not the the images represented by this image format are grayscale.\n */\n@property (nonatomic, assign, readonly) BOOL isGrayscale;\n\n/**\n The data protection mode that image table files will be created with.\n \n `FICImageFormatProtectionMode` has the following values:\n \n - `FICImageFormatProtectionModeNone`: No data protection is used. The image table file backing this image format will always be available for reading and writing.\n - `FICImageFormatProtectionModeComplete`: Complete data protection is used. As soon as the system enables data protection (i.e., when the device is locked), the image table file backing this image\n format will not be available for reading and writing. As a result, images of this format should not be requested by Fast Image Cache when executing backgrounded code.\n - `FICImageFormatProtectionModeCompleteUntilFirstUserAuthentication`: Partial data protection is used. After a device restart, until the user unlocks the device for the first time, complete data\n protection is in effect. However, after the device has been unlocked for the first time, the image table file backing this image format will remain available for readin and writing. This mode may be\n a good compromise between encrypting image table files after the device powers down and allowing the files to be accessed successfully by Fast Image Cache, whether or not the device is subsequently\n locked.\n \n @note Data protection can prevent Fast Image Cache from accessing its image table files to read and write image data. If the image data being stored in Fast Image Cache is not sensitive in nature,\n consider using `FICImageFormatProtectionModeNone` to prevent any issues accessing image table files when the disk is encrypted.\n */\n@property (nonatomic, assign) FICImageFormatProtectionMode protectionMode;\n\n/**\n The string representation of ``.\n */\n@property (nonatomic, assign, readonly) NSString *protectionModeString;\n\n/**\n The dictionary representation of this image format.\n \n @discussion Fast Image Cache automatically serializes the image formats that it uses to disk. If an image format ever changes, Fast Image Cache automatically detects the change and invalidates the\n image table associated with that image format. The image table is then recreated from the updated image format.\n */\n@property (nonatomic, copy, readonly) NSDictionary *dictionaryRepresentation;\n\n///-----------------------------------\n/// @name Initializing an Image Format\n///-----------------------------------\n\n/**\n Convenience initializer to create a new image format.\n \n @param name The name of the image format. Each image format must have a unique name.\n \n @param family The optional family that the image format belongs to. See the `` property description for more information.\n \n @param imageSize The size, in points, of the images stored in the image table created by this format.\n \n @param style The style of the image format. See the `