112 lines
4.3 KiB
Objective-C
112 lines
4.3 KiB
Objective-C
//
|
|
// RZDBCoalesce.h
|
|
//
|
|
// Created by Rob Visentin on 4/1/15.
|
|
|
|
// Copyright 2014 Raizlabs and other contributors
|
|
// http://raizlabs.com/
|
|
//
|
|
// Permission is hereby granted, free of charge, to any person obtaining
|
|
// a copy of this software and associated documentation files (the
|
|
// "Software"), to deal in the Software without restriction, including
|
|
// without limitation the rights to use, copy, modify, merge, publish,
|
|
// distribute, sublicense, and/or sell copies of the Software, and to
|
|
// permit persons to whom the Software is furnished to do so, subject to
|
|
// the following conditions:
|
|
//
|
|
// The above copyright notice and this permission notice shall be
|
|
// included in all copies or substantial portions of the Software.
|
|
//
|
|
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
//
|
|
|
|
#import <Foundation/Foundation.h>
|
|
|
|
#pragma mark - NSObject+RZDBCoalesce interface
|
|
|
|
/**
|
|
* Provides an interface for supporting coalesced data binding callbacks.
|
|
*/
|
|
@interface NSObject (RZDBCoalesce)
|
|
|
|
/**
|
|
* Returns a proxy object that will participate in coalescing events.
|
|
*
|
|
* Use [target rz_coalesceProxy] as the target of the rz_addTarget:action: methods to support
|
|
* coalescing for a target/action pair. If the callback occurs during a an RZDBCoalesce event, it will be
|
|
* coalesced and deferred until the end RZDBCoalesce is committed.
|
|
*
|
|
* @note You should generally not call methods on the coalesce proxy directly.
|
|
* The proxy will treat any 0-arg or 1-dictionary-arg methods with void return type as RZDB callbacks,
|
|
* and coalesce them accordingly.
|
|
*
|
|
* @see RZDBCoalesce for how to begin/end coalesce events.
|
|
*
|
|
* @return A proxy object to use as a data binding target in the rz_addTarget:action: methods.
|
|
*/
|
|
- (id)rz_coalesceProxy;
|
|
|
|
@end
|
|
|
|
#pragma mark - RZDBCoalesce interface
|
|
|
|
/**
|
|
* There may be chunks of work that should be completed "atomically" with respect to RZDataBinding.
|
|
* That is, actions registered using the rz_addTarget:action: methods that support coalescing
|
|
* will be fired once, when the work is completed.
|
|
*
|
|
* The RZDBCoalesce object provides class methods to manage coalescing events.
|
|
*
|
|
* Coalescing is an advanced feature that should generally only be used if you encounter a performance issue,
|
|
* or find some other requirement for it.
|
|
*
|
|
* @see NSObject+RZDBCoalesce for how to support coalesced callbacks.
|
|
*/
|
|
@interface RZDBCoalesce : NSObject
|
|
|
|
/**
|
|
* Begin coalescing events for the current thread.
|
|
* Changes that occur during the coalesce that would trigger actions registered to coalesce proxies with
|
|
* the rz_addTarget:action: methods are instead coalesced and executed once when the coalesce ends.
|
|
*
|
|
* Every call to +begin MUST be balanced by a call to +commit on the same thread.
|
|
* It is fine to begin a coalesce while already coalescing--
|
|
* the coalesce will simply not end until both matching commits are hit.
|
|
*
|
|
* @note Bindings that occur during a coalesce still occur immediately.
|
|
*
|
|
* @see NSObject+RZDBCoalesce for how to support coalesced callbacks.
|
|
*/
|
|
+ (void)begin;
|
|
|
|
/**
|
|
* Commit the current coalesce, sending the coalesced change callbacks.
|
|
* If this commit closes a nested coalesce, callbacks are not sent until the outermost coalesce is committed.
|
|
*
|
|
* Calling this method from outside a coalesce has no effect.
|
|
*/
|
|
+ (void)commit;
|
|
|
|
/**
|
|
* Convenience method that first calls +begin, then executes the block, then calls +commit.
|
|
* You should prefer this method where possible to avoid programmer error (i.e. forgetting to call +commit).
|
|
*
|
|
* @param coalesceBlock The block to execute inside a coalesce. Must be non-nil.
|
|
*
|
|
* @see NSObject+RZDBCoalesce for how to support coalesced callbacks.
|
|
*/
|
|
+ (void)coalesceBlock:(void (^)())coalesceBlock;
|
|
|
|
/**
|
|
* Cannot instantiate RZDBCoalesce directly. Use the class methods instead.
|
|
*/
|
|
- (instancetype)init __attribute__((unavailable("Cannot instantiate RZDBCoalesce directly. Use the class methods instead.")));
|
|
|
|
@end
|