xylxi / MessageThrottle

A lightweight Objective-C message throttle and debounce library.

Home Page:http://yulingtianxia.com/blog/2017/11/05/Objective-C-Message-Throttle-and-Debounce/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

MessageThrottle

CI Status Version Carthage compatible License Platform

MessageThrottle is a lightweight, simple library for controlling frequency of forwarding Objective-C messages. You can choose to control existing methods per instance or per class. It's an implementation of function throttle/debounce developed with Objective-C runtime. For a visual explaination of the differences between throttling and debouncing, see this demo.

Usage

The following example shows how to restrict the frequency of forwarding - [ViewController foo:] message to 10 times per second.

Stub *s = [Stub new];
MTRule *rule = [MTRule new];
rule.target = s; // You can also assign `Stub.class` or `mt_metaClass(Stub.class)`
rule.selector = @selector(foo:);
rule.durationThreshold = 0.01;
[MTEngine.defaultEngine applyRule:rule];

MTRule represents the rule of a message throttle, which contains strategy and frequency of sending messages.

You can assign an instance or (meta)class to target property. When you assign an instance to target, MessageThrottle will only restrict messages send to this instance. If you want to restrict a class method, just using mt_metaClass() to get it's meta class, and assign the meta class to target. Rules with instance target won't conflict with each other, and have a higher priority than rules with class target.

MTRule also define the mode of performing selector. There are three modes defined in MTMode: MTModePerformFirstly, MTModePerformLast and MTModePerformDebounce.

The default mode is MTModePerformDebounce. MTModePerformDebounce will restart timer when another message arrives during durationThreshold. So there must be a delay of durationThreshold at least.

MTModePerformDebounce:
start                                        end
|           durationThreshold(old)             |
@----------------------@---------------------->>
|                      |                 
ignore                 will perform at end of new duration
                       |--------------------------------------------->>
                       |           durationThreshold(new)             |
                       start                                        end

MTModePerformFirstly will performs the first message and ignore all following messages during durationThreshold.

MTModePerformFirstly:
start                                                                end
|                           durationThreshold                          |
@-------------------------@----------@---------------@---------------->>
|                         |          |               |          
perform immediately       ignore     ignore          ignore     

MTModePerformLast performs the last message at end time. Please note that does not perform message immediately, the delay could be durationThreshold at most.

MTModePerformLast:
start                                                                end
|                           durationThreshold                          |
@-------------------------@----------@---------------@---------------->>
|                         |          |               |          
ignore                    ignore     ignore          will perform at end

When using MTModePerformLast or MTModePerformDebounce, you can designate a dispatch queue which messages perform on. The messageQueue is main queue by default. MTModePerformLast and MTModePerformDebounce modes will also use the last arguments to perform messages.

MTEngine is a singleton class. It manages all rules of message throttles. You can use applyRule: method to apply a rule or update an old rule that already exists. Using it's discardRule: method to discardRule a rule. There is also a readonly property allRules for obtaining all rules in current application.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate MessageThrottle into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!
target 'MyApp' do
	pod 'MessageThrottle'
end

You need replace "MyApp" with your project's name.

Then, run the following command:

$ pod install

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate MessageThrottle into your Xcode project using Carthage, specify it in your Cartfile:

github "yulingtianxia/MessageThrottle"

Run carthage update to build the framework and drag the built MessageThrottleKit.framework into your Xcode project.

Manual

Just drag the "MessageThrottle" document folder into your project.

Contributing

  • If you need help or you'd like to ask a general question, open an issue.
  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, submit a pull request.

Article

Author

yulingtianxia, yulingtianxia@gmail.com

License

MessageThrottle is available under the MIT license. See the LICENSE file for more info.

About

A lightweight Objective-C message throttle and debounce library.

http://yulingtianxia.com/blog/2017/11/05/Objective-C-Message-Throttle-and-Debounce/

License:MIT License


Languages

Language:Objective-C 96.2%Language:Ruby 3.8%