BlockHook
Hook Objective-C blocks with libffi. It's a powerful AOP tool for blocks. BlockHook can run your code before/instead/after invoking a block. BlockHook can even notify you when a block dealloc. You can trace the whole lifecycle of a block using BlockHook!
📚 Article
🌟 Features
- Easy to use.
- Keep your code clear.
- Reserve the whole arguments.
- Support 4 hook modes: Before, Instead, After and Dead.
- Use tokens to change hook mode dynamically.
- Modify return value.
- Support invoking original implementation.
- Self-managed tokens.
- Support Carthage.
🔮 Example
BlockHook needs libffi, which is a submodule in this project. You should use --recursive
when clone this sample, or you can use these commands get the submodule.
cd libffi
git submodule init
git submodule update
If targets in Xcode fails to compile, you need do these in libffi folder:
- run
./autogen.sh
- run
./configure
- run
python generate-darwin-source-and-headers.py
The sample project "BlockHookSample" just only support iOS platform. You must build libffi for every architecture you need.
🐒 How to use
You can hook a block using 4 modes (before/instead/after/dead). This method returns a BHToken
instance for more control. You can remove
a BHToken
, or set custom return value to its retValue
property. Calling invokeOriginalBlock
method will invoke original implementation of the block.
- (BHToken *)block_hookWithMode:(BlockHookMode)mode
usingBlock:(id)block
BlockHook is easy to use. Its APIs take example by Aspects. Here is a full set of usage of BlockHook.
NSObject *z = NSObject.new;
int (^block)(int, int) = ^(int x, int y) {
int result = x + y;
NSLog(@"%d + %d = %d, z is a NSObject: %p", x, y, result, z);
return result;
};
BHToken *tokenInstead = [block block_hookWithMode:BlockHookModeInstead usingBlock:^(BHToken *token, int x, int y){
[token invokeOriginalBlock];
NSLog(@"let me see original result: %d", *(int *)(token.retValue));
// change the block imp and result
*(int *)(token.retValue) = x * y;
NSLog(@"hook instead: '+' -> '*'");
}];
BHToken *tokenAfter = [block block_hookWithMode:BlockHookModeAfter usingBlock:^(BHToken *token, int x, int y){
// print args and result
NSLog(@"hook after block! %d * %d = %d", x, y, *(int *)(token.retValue));
}];
BHToken *tokenBefore = [block block_hookWithMode:BlockHookModeBefore usingBlock:^(id token){
// BHToken has to be the first arg.
NSLog(@"hook before block! token:%@", token);
}];
BHToken *tokenDead = [block block_hookWithMode:BlockHookModeDead usingBlock:^(id token){
// BHToken is the only arg.
NSLog(@"block dead! token:%@", token);
}];
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
NSLog(@"hooked block");
int ret = block(3, 5);
NSLog(@"hooked result:%d", ret);
// remove all tokens when you don't need.
// reversed order of hook.
[tokenBefore remove];
[tokenAfter remove];
[tokenInstead remove];
NSLog(@"remove tokens, original block");
ret = block(3, 5);
NSLog(@"original result:%d", ret);
// [tokenDead remove];
});
Here is the log:
hooked block
hook before block! token:<BHToken: 0x1d00f0d80>
3 + 5 = 8, z is a NSObject: 0x1d00172b0
let me see original result: 8
hook instead: '+' -> '*'
hook after block! 3 * 5 = 15
hooked result:15
remove tokens, original block
3 + 5 = 8, z is a NSObject: 0x1d00172b0
original result:8
block dead! token:<BHToken: 0x1d00f9900>
📲 Installation
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 BlockHook into your Xcode project using Carthage, specify it in your Cartfile
:
github "yulingtianxia/BlockHook"
Run carthage update
to build the framework and drag the built BlockHookKit.framework
into your Xcode project.
Manual
After importing libffi, just add the two files BlockHook.h/m
to your project.
❤️ Contributed
- 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.
👨🏻💻 Author
yulingtianxia, yulingtianxia@gmail.com
👮🏻 License
BlockHook is available under the MIT license. See the LICENSE file for more info.
Thanks to MABlockClosure and Aspects!