Merge pull request SDWebImage#3465 from dreampiggy/feat/callback_queue

Added context option `callbackQueue` and `SDCallbackQueue` wrapper for advanced user to control which queue to callback

Author: dreampiggy

SDWebImage.xcodeproj/project.pbxproj

@@ -25,6 +25,8 @@
 		320CAE172086F50500CFFC80 /* SDWebImageError.h in Headers */ = {isa = PBXBuildFile; fileRef = 320CAE132086F50500CFFC80 /* SDWebImageError.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		320CAE1B2086F50500CFFC80 /* SDWebImageError.m in Sources */ = {isa = PBXBuildFile; fileRef = 320CAE142086F50500CFFC80 /* SDWebImageError.m */; };
 		320CAE1D2086F50500CFFC80 /* SDWebImageError.m in Sources */ = {isa = PBXBuildFile; fileRef = 320CAE142086F50500CFFC80 /* SDWebImageError.m */; };
+		321117A9296573680001FC2C /* SDCallbackQueue.h in Headers */ = {isa = PBXBuildFile; fileRef = 321117A7296573680001FC2C /* SDCallbackQueue.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		321117AA296573680001FC2C /* SDCallbackQueue.m in Sources */ = {isa = PBXBuildFile; fileRef = 321117A8296573680001FC2C /* SDCallbackQueue.m */; };
 		321B37832083290E00C0EA77 /* SDImageLoader.h in Headers */ = {isa = PBXBuildFile; fileRef = 321B377D2083290D00C0EA77 /* SDImageLoader.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		321B37872083290E00C0EA77 /* SDImageLoader.m in Sources */ = {isa = PBXBuildFile; fileRef = 321B377E2083290D00C0EA77 /* SDImageLoader.m */; };
 		321B37892083290E00C0EA77 /* SDImageLoader.m in Sources */ = {isa = PBXBuildFile; fileRef = 321B377E2083290D00C0EA77 /* SDImageLoader.m */; };
@@ -67,6 +69,7 @@
 		324DF4B6200A14DC008A84CC /* SDWebImageDefine.h in Headers */ = {isa = PBXBuildFile; fileRef = 324DF4B2200A14DC008A84CC /* SDWebImageDefine.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		324DF4BA200A14DC008A84CC /* SDWebImageDefine.m in Sources */ = {isa = PBXBuildFile; fileRef = 324DF4B3200A14DC008A84CC /* SDWebImageDefine.m */; };
 		324DF4BC200A14DC008A84CC /* SDWebImageDefine.m in Sources */ = {isa = PBXBuildFile; fileRef = 324DF4B3200A14DC008A84CC /* SDWebImageDefine.m */; };
+		325074F2296C546D00B730CF /* SDCallbackQueue.h in Copy Headers */ = {isa = PBXBuildFile; fileRef = 321117A7296573680001FC2C /* SDCallbackQueue.h */; };
 		3250C9EE2355D9DA0093A896 /* SDWebImageDownloaderDecryptor.h in Headers */ = {isa = PBXBuildFile; fileRef = 3250C9EC2355D9DA0093A896 /* SDWebImageDownloaderDecryptor.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		3250C9EF2355D9DA0093A896 /* SDWebImageDownloaderDecryptor.m in Sources */ = {isa = PBXBuildFile; fileRef = 3250C9ED2355D9DA0093A896 /* SDWebImageDownloaderDecryptor.m */; };
 		3250C9F02355D9DA0093A896 /* SDWebImageDownloaderDecryptor.m in Sources */ = {isa = PBXBuildFile; fileRef = 3250C9ED2355D9DA0093A896 /* SDWebImageDownloaderDecryptor.m */; };
@@ -317,6 +320,7 @@
 			dstPath = include/SDWebImage;
 			dstSubfolderSpec = 16;
 			files = (
+				325074F2296C546D00B730CF /* SDCallbackQueue.h in Copy Headers */,
 				32D9EE4B24AF259B00EAFDF4 /* SDImageAWebPCoder.h in Copy Headers */,
 				328E9DE523A61DD30051C893 /* SDGraphicsImageRenderer.h in Copy Headers */,
 				325F7CCD2389467800AEDFCC /* UIImage+ExtendedCacheData.h in Copy Headers */,
@@ -387,6 +391,8 @@
 		320224BA203979BA00E9F285 /* SDAnimatedImageRep.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = SDAnimatedImageRep.m; path = Core/SDAnimatedImageRep.m; sourceTree = "<group>"; };
 		320CAE132086F50500CFFC80 /* SDWebImageError.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = SDWebImageError.h; path = Core/SDWebImageError.h; sourceTree = "<group>"; };
 		320CAE142086F50500CFFC80 /* SDWebImageError.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = SDWebImageError.m; path = Core/SDWebImageError.m; sourceTree = "<group>"; };
+		321117A7296573680001FC2C /* SDCallbackQueue.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = SDCallbackQueue.h; path = Core/SDCallbackQueue.h; sourceTree = "<group>"; };
+		321117A8296573680001FC2C /* SDCallbackQueue.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = SDCallbackQueue.m; path = Core/SDCallbackQueue.m; sourceTree = "<group>"; };
 		321B377D2083290D00C0EA77 /* SDImageLoader.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SDImageLoader.h; path = Core/SDImageLoader.h; sourceTree = "<group>"; };
 		321B377E2083290D00C0EA77 /* SDImageLoader.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = SDImageLoader.m; path = Core/SDImageLoader.m; sourceTree = "<group>"; };
 		321B377F2083290E00C0EA77 /* SDImageLoadersManager.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SDImageLoadersManager.h; path = Core/SDImageLoadersManager.h; sourceTree = "<group>"; };
@@ -872,6 +878,8 @@
 				325312C7200F09910046BF1E /* SDWebImageTransition.m */,
 				32C0FDDF2013426C001B8F2D /* SDWebImageIndicator.h */,
 				32C0FDE02013426C001B8F2D /* SDWebImageIndicator.m */,
+				321117A7296573680001FC2C /* SDCallbackQueue.h */,
+				321117A8296573680001FC2C /* SDCallbackQueue.m */,
 			);
 			name = Utils;
 			sourceTree = "<group>";
@@ -957,6 +965,7 @@
 				3250C9EE2355D9DA0093A896 /* SDWebImageDownloaderDecryptor.h in Headers */,
 				32F7C0862030719600873181 /* UIImage+Transform.h in Headers */,
 				321E60C01F38E91700405457 /* UIImage+ForceDecode.h in Headers */,
+				321117A9296573680001FC2C /* SDCallbackQueue.h in Headers */,
 				329F1243223FAD3400B309FD /* SDInternalMacros.h in Headers */,
 				80B6DF7F2142B43300BCB334 /* NSImage+Compatibility.h in Headers */,
 				32C0FDE32013426C001B8F2D /* SDWebImageIndicator.h in Headers */,
@@ -1205,6 +1214,7 @@
 				4A2CAE221AB4BB7000B6BC39 /* SDWebImageManager.m in Sources */,
 				4A2CAE191AB4BB6400B6BC39 /* SDWebImageCompat.m in Sources */,
 				325C460B22339426004CAE11 /* SDWeakProxy.m in Sources */,
+				321117AA296573680001FC2C /* SDCallbackQueue.m in Sources */,
 				321B37892083290E00C0EA77 /* SDImageLoader.m in Sources */,
 				32484771201775F600AF9E5A /* SDAnimatedImage.m in Sources */,
 				807A12301F89636300EC2A9B /* SDImageCodersManager.m in Sources */,

SDWebImage/Core/SDCallbackQueue.h

@@ -0,0 +1,54 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+
+#import "SDWebImageCompat.h"
+
+/// SDCallbackPolicy controls how we execute the block on the queue, like whether to use `dispatch_async/dispatch_sync`, check if current queue match target queue, or just invoke without any context.
+typedef NS_ENUM(NSUInteger, SDCallbackPolicy) {
+    /// When the current queue is equal to callback queue, sync/async will just invoke `block` directly without dispatch. Else it use `dispatch_async`/`dispatch_sync` to dispatch block on queue. This is useful for UIKit rendering to ensure all blocks executed in the same runloop
+    SDCallbackPolicySafeExecute = 0,
+    /// Follow async/sync using the correspond `dispatch_async`/`dispatch_sync` to dispatch block on queue
+    SDCallbackPolicyDispatch = 1,
+    /// Ignore any async/sync and just directly invoke `block` in current queue (without `dispatch_async`/`dispatch_sync`)
+    SDCallbackPolicyInvoke = 2
+};
+
+/// SDCallbackQueue is a wrapper used to control how the completionBlock should perform on queues, used by our `Cache`/`Manager`/`Loader`.
+/// Useful when you call SDWebImage in non-main queue and want to avoid it callback into main queue, which may cause issue.
+@interface SDCallbackQueue : NSObject
+
+/// The shared main queue. This is the default value, has the same effect when passing `nil` to `SDWebImageContextCallbackQueue`
+@property (nonnull, class, readonly) SDCallbackQueue *mainQueue;
+
+/// The caller current queue. Using `dispatch_get_current_queue`. This is not a dynamic value and only keep the first call time queue.
+@property (nonnull, class, readonly) SDCallbackQueue *currentQueue;
+
+/// The global concurrent queue (user-initiated QoS). Using `dispatch_get_global_queue`.
+@property (nonnull, class, readonly) SDCallbackQueue *globalQueue;
+
+/// The current queue's callback policy, defaults to `SDCallbackPolicySafeExecute`, which behaves like the old macro  `dispatch_main_async_safe`
+@property (assign, readwrite) SDCallbackPolicy policy;
+
+- (nonnull instancetype)init NS_UNAVAILABLE;
++ (nonnull instancetype)new  NS_UNAVAILABLE;
+/// Create the callback queue with a GCD queue
+/// - Parameter queue: The GCD queue, should not be NULL
+- (nonnull instancetype)initWithDispatchQueue:(nonnull dispatch_queue_t)queue NS_DESIGNATED_INITIALIZER;
+
+#pragma mark - Execution Entry
+
+/// Submits a block for execution and returns after that block finishes executing.
+/// - Parameter block: The block that contains the work to perform.
+- (void)sync:(nonnull NS_NOESCAPE dispatch_block_t)block;
+
+/// Schedules a block asynchronously for execution.
+/// - Parameter block: The block that contains the work to perform.
+- (void)async:(nonnull NS_NOESCAPE dispatch_block_t)block;
+
+@end

SDWebImage/Core/SDCallbackQueue.m

@@ -0,0 +1,110 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+
+#import "SDCallbackQueue.h"
+
+@interface SDCallbackQueue ()
+
+@property (nonatomic, strong, nonnull) dispatch_queue_t queue;
+
+@end
+
+static void * SDCallbackQueueKey = &SDCallbackQueueKey;
+static void SDReleaseBlock(void *context) {
+    CFRelease(context);
+}
+
+static void inline SDSafeExecute(dispatch_queue_t _Nonnull queue, dispatch_block_t _Nonnull block, BOOL async) {
+    // Special handle for main queue label only (custom queue can have the same label)
+    const char *label = dispatch_queue_get_label(queue);
+    if (label && label == dispatch_queue_get_label(dispatch_get_main_queue())) {
+        const char *currentLabel = dispatch_queue_get_label(DISPATCH_CURRENT_QUEUE_LABEL);
+        if (label == currentLabel) {
+            block();
+            return;
+        }
+    }
+    // Check specific to detect queue equal
+    void *specific = dispatch_queue_get_specific(queue, SDCallbackQueueKey);
+    void *currentSpecific = dispatch_get_specific(SDCallbackQueueKey);
+    if (specific && currentSpecific && CFGetTypeID(specific) == CFUUIDGetTypeID() && CFGetTypeID(currentSpecific) == CFUUIDGetTypeID() && CFEqual(specific, currentSpecific)) {
+        block();
+    } else {
+        if (async) {
+            dispatch_async(queue, block);
+        } else {
+            dispatch_sync(queue, block);
+        }
+    }
+}
+
+@implementation SDCallbackQueue
+
+- (instancetype)initWithDispatchQueue:(dispatch_queue_t)queue {
+    self = [super init];
+    if (self) {
+        NSCParameterAssert(queue);
+        CFUUIDRef UUID = CFUUIDCreate(kCFAllocatorDefault);
+        dispatch_queue_set_specific(queue, SDCallbackQueueKey, (void *)UUID, SDReleaseBlock);
+        _queue = queue;
+    }
+    return self;
+}
+
++ (SDCallbackQueue *)mainQueue {
+    static dispatch_once_t onceToken;
+    static SDCallbackQueue *queue;
+    dispatch_once(&onceToken, ^{
+        queue = [[SDCallbackQueue alloc] initWithDispatchQueue:dispatch_get_main_queue()];
+    });
+    return queue;
+}
+
++ (SDCallbackQueue *)currentQueue {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    SDCallbackQueue *queue = [[SDCallbackQueue alloc] initWithDispatchQueue:dispatch_get_current_queue()];
+#pragma clang diagnostic pop
+    return queue;
+}
+
++ (SDCallbackQueue *)globalQueue {
+    SDCallbackQueue *queue = [[SDCallbackQueue alloc] initWithDispatchQueue:dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0)];
+    return queue;
+}
+
+- (void)sync:(nonnull NS_NOESCAPE dispatch_block_t)block {
+    switch (self.policy) {
+        case SDCallbackPolicySafeExecute:
+            SDSafeExecute(self.queue, block, NO);
+            break;
+        case SDCallbackPolicyDispatch:
+            dispatch_sync(self.queue, block);
+            break;
+        case SDCallbackPolicyInvoke:
+            block();
+            break;
+    }
+}
+
+- (void)async:(nonnull NS_NOESCAPE dispatch_block_t)block {
+    switch (self.policy) {
+        case SDCallbackPolicySafeExecute:
+            SDSafeExecute(self.queue, block, YES);
+            break;
+        case SDCallbackPolicyDispatch:
+            dispatch_async(self.queue, block);
+            break;
+        case SDCallbackPolicyInvoke:
+            block();
+            break;
+    }
+}
+
+@end

SDWebImage/Core/SDImageCache.h

@@ -225,6 +225,28 @@ typedef NS_OPTIONS(NSUInteger, SDImageCacheOptions) {
             toDisk:(BOOL)toDisk
         completion:(nullable SDWebImageNoParamsBlock)completionBlock;
 
+/**
+ * Asynchronously store an image into memory and disk cache at the given key.
+ *
+ * @param image           The image to store
+ * @param imageData       The image data as returned by the server, this representation will be used for disk storage
+ *                        instead of converting the given image object into a storable/compressed image format in order
+ *                        to save quality and CPU
+ * @param key             The unique image cache key, usually it's image absolute URL
+ * @param options A mask to specify options to use for this store
+ * @param context The context options to use. Pass `.callbackQueue` to control callback queue
+ * @param cacheType The image store op cache type
+ * @param completionBlock A block executed after the operation is finished
+ * @note If no image data is provided and encode to disk, we will try to detect the image format (using either `sd_imageFormat` or `SDAnimatedImage` protocol method) and animation status, to choose the best matched format, including GIF, JPEG or PNG.
+ */
+- (void)storeImage:(nullable UIImage *)image
+         imageData:(nullable NSData *)imageData
+            forKey:(nullable NSString *)key
+           options:(SDWebImageOptions)options
+           context:(nullable SDWebImageContext *)context
+         cacheType:(SDImageCacheType)cacheType
+        completion:(nullable SDWebImageNoParamsBlock)completionBlock;
+
 /**
  * Synchronously store an image into memory cache at the given key.
  *