Name: ReactiveObjC
Owner: ReactiveCocoa
Description: The 2.x ReactiveCocoa Objective-C API: Streams of values over time
Created: 2016-05-12 03:04:05.0
Updated: 2018-05-24 18:04:32.0
Pushed: 2017-12-30 17:05:59.0
Homepage: null
Size: 14270
Language: Objective-C
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
NOTE: This is legacy introduction to the Objective-C ReactiveCocoa, which is now known as ReactiveObjC. For the updated version that uses Swift, please see ReactiveCocoa or ReactiveSwift
ReactiveObjC (formally ReactiveCocoa or RAC) is an Objective-C framework inspired by Functional Reactive Programming. It provides APIs for composing and transforming streams of values.
If you're already familiar with functional reactive programming or know the basic premise of ReactiveObjC, check out the other documentation in this folder for a framework overview and more in-depth information about how it all works in practice.
ReactiveObjC is documented like crazy, and there's a wealth of introductory material available to explain what RAC is and how you can use it.
If you want to learn more, we recommend these resources, roughly in order:
If you have any further questions, please feel free to file an issue.
ReactiveObjC is inspired by functional reactive programming.
Rather than using mutable variables which are replaced and modified in-place,
RAC provides signals (represented by RACSignal) that capture present and
future values.
By chaining, combining, and reacting to signals, software can be written declaratively, without the need for code that continually observes and updates values.
For example, a text field can be bound to the latest time, even as it changes,
instead of using additional code that watches the clock and updates the
text field every second. It works much like KVO, but with blocks instead of
overriding -observeValueForKeyPath:ofObject:change:context:.
Signals can also represent asynchronous operations, much like futures and promises. This greatly simplifies asynchronous software, including networking code.
One of the major advantages of RAC is that it provides a single, unified approach to dealing with asynchronous behaviors, including delegate methods, callback blocks, target-action mechanisms, notifications, and KVO.
Here's a simple example:
hen self.username changes, logs the new name to the console.
ACObserve(self, username) creates a new RACSignal that sends the current
alue of self.username, then the new value whenever it changes.
subscribeNext: will execute the block whenever the signal sends a value.
Observe(self, username) subscribeNext:^(NSString *newName) {
NSLog(@"%@", newName);
But unlike KVO notifications, signals can be chained together and operated on:
nly logs names that starts with "j".
filter returns a new RACSignal that only sends a new value when its block
eturns YES.
CObserve(self, username)
filter:^(NSString *newName) {
return [newName hasPrefix:@"j"];
}]
subscribeNext:^(NSString *newName) {
NSLog(@"%@", newName);
}];
Signals can also be used to derive state. Instead of observing properties and setting other properties in response to the new values, RAC makes it possible to express properties in terms of signals and operations:
reates a one-way binding so that self.createEnabled will be
rue whenever self.password and self.passwordConfirmation
re equal.
AC() is a macro that makes the binding look nicer.
combineLatest:reduce: takes an array of signals, executes the block with the
atest value from each signal whenever any of them changes, and returns a new
ACSignal that sends the return value of that block as values.
self, createEnabled) = [RACSignal
combineLatest:@[ RACObserve(self, password), RACObserve(self, passwordConfirmation) ]
reduce:^(NSString *password, NSString *passwordConfirm) {
return @([passwordConfirm isEqualToString:password]);
}];
Signals can be built on any stream of values over time, not just KVO. For example, they can also represent button presses:
ogs a message whenever the button is pressed.
ACCommand creates signals to represent UI actions. Each signal can
epresent a button press, for example, and have additional work associated
ith it.
rac_command is an addition to NSButton. The button will send itself on that
ommand whenever it's pressed.
.button.rac_command = [[RACCommand alloc] initWithSignalBlock:^(id _) {
NSLog(@"button was pressed!");
return [RACSignal empty];
Or asynchronous network operations:
ooks up a "Log in" button to log in over the network.
his block will be run whenever the login command is executed, starting
he login process.
.loginCommand = [[RACCommand alloc] initWithSignalBlock:^(id sender) {
// The hypothetical -logIn method returns a signal that sends a value when
// the network request finishes.
return [client logIn];
executionSignals returns a signal that includes the signals returned from
he above block, one for each time the command is executed.
f.loginCommand.executionSignals subscribeNext:^(RACSignal *loginSignal) {
// Log a message whenever we log in successfully.
[loginSignal subscribeCompleted:^{
NSLog(@"Logged in successfully!");
}];
xecutes the login command when the button is pressed.
.loginButton.rac_command = self.loginCommand;
Signals can also represent timers, other UI events, or anything else that changes over time.
Using signals for asynchronous operations makes it possible to build up more complex behavior by chaining and transforming those signals. Work can easily be triggered after a group of operations completes:
erforms 2 network operations and logs a message to the console when they are
oth completed.
merge: takes an array of signals and returns a new RACSignal that passes
hrough the values of all of the signals and completes when all of the
ignals complete.
subscribeCompleted: will execute the block when the signal completes.
CSignal
merge:@[ [client fetchUserRepos], [client fetchOrgRepos] ]]
subscribeCompleted:^{
NSLog(@"They're both done!");
}];
Signals can be chained to sequentially execute asynchronous operations, instead of nesting callbacks with blocks. This is similar to how futures and promises are usually used:
ogs in the user, then loads any cached messages, then fetches the remaining
essages from the server. After that's all done, logs a message to the
onsole.
he hypothetical -logInUser methods returns a signal that completes after
ogging in.
flattenMap: will execute its block whenever the signal sends a value, and
eturns a new RACSignal that merges all of the signals returned from the block
nto a single signal.
client
logInUser]
flattenMap:^(User *user) {
// Return a signal that loads cached messages for the user.
return [client loadCachedMessagesForUser:user];
}]
flattenMap:^(NSArray *messages) {
// Return a signal that fetches any remaining messages.
return [client fetchMessagesAfterMessage:messages.lastObject];
}]
subscribeNext:^(NSArray *newMessages) {
NSLog(@"New messages: %@", newMessages);
} completed:^{
NSLog(@"Fetched all messages.");
}];
RAC even makes it easy to bind to the result of an asynchronous operation:
reates a one-way binding so that self.imageView.image will be set as the user's
vatar as soon as it's downloaded.
he hypothetical -fetchUserWithUsername: method returns a signal which sends
he user.
deliverOn: creates new signals that will do their work on other queues. In
his example, it's used to move work to a background queue and then back to the main thread.
map: calls its block with each user that's fetched and returns a new
ACSignal that sends values returned from the block.
self.imageView, image) = [[[[client
fetchUserWithUsername:@"joshaber"]
deliverOn:[RACScheduler scheduler]]
map:^(User *user) {
// Download the avatar (this is done on a background queue).
return [[NSImage alloc] initWithContentsOfURL:user.avatarURL];
}]
// Now the assignment will be done on the main thread.
deliverOn:RACScheduler.mainThreadScheduler];
That demonstrates some of what RAC can do, but it doesn't demonstrate why RAC is so powerful. It's hard to appreciate RAC from README-sized examples, but it makes it possible to write code with less state, less boilerplate, better code locality, and better expression of intent.
For more sample code, check out C-41 or GroceryList, which are real iOS apps written using ReactiveObjC. Additional information about RAC can be found in this folder.
Upon first glance, ReactiveObjC is very abstract, and it can be difficult to understand how to apply it to concrete problems.
Here are some of the use cases that RAC excels at.
Much of Cocoa programming is focused on reacting to user events or changes in application state. Code that deals with such events can quickly become very complex and spaghetti-like, with lots of callbacks and state variables to handle ordering issues.
Patterns that seem superficially different, like UI callbacks, network responses, and KVO notifications, actually have a lot in common. RACSignal unifies all these different APIs so that they can be composed together and manipulated in the same way.
For example, the following code:
ic void *ObservationContext = &ObservationContext;
oid)viewDidLoad {
[super viewDidLoad];
[LoginManager.sharedManager addObserver:self forKeyPath:@"loggingIn" options:NSKeyValueObservingOptionInitial context:&ObservationContext];
[NSNotificationCenter.defaultCenter addObserver:self selector:@selector(loggedOut:) name:UserDidLogOutNotification object:LoginManager.sharedManager];
[self.usernameTextField addTarget:self action:@selector(updateLogInButton) forControlEvents:UIControlEventEditingChanged];
[self.passwordTextField addTarget:self action:@selector(updateLogInButton) forControlEvents:UIControlEventEditingChanged];
[self.logInButton addTarget:self action:@selector(logInPressed:) forControlEvents:UIControlEventTouchUpInside];
oid)dealloc {
[LoginManager.sharedManager removeObserver:self forKeyPath:@"loggingIn" context:ObservationContext];
[NSNotificationCenter.defaultCenter removeObserver:self];
oid)updateLogInButton {
BOOL textFieldsNonEmpty = self.usernameTextField.text.length > 0 && self.passwordTextField.text.length > 0;
BOOL readyToLogIn = !LoginManager.sharedManager.isLoggingIn && !self.loggedIn;
self.logInButton.enabled = textFieldsNonEmpty && readyToLogIn;
BAction)logInPressed:(UIButton *)sender {
[[LoginManager sharedManager]
logInWithUsername:self.usernameTextField.text
password:self.passwordTextField.text
success:^{
self.loggedIn = YES;
} failure:^(NSError *error) {
[self presentError:error];
}];
oid)loggedOut:(NSNotification *)notification {
self.loggedIn = NO;
oid)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context {
if (context == ObservationContext) {
[self updateLogInButton];
} else {
[super observeValueForKeyPath:keyPath ofObject:object change:change context:context];
}
? could be expressed in RAC like so:
oid)viewDidLoad {
[super viewDidLoad];
@weakify(self);
RAC(self.logInButton, enabled) = [RACSignal
combineLatest:@[
self.usernameTextField.rac_textSignal,
self.passwordTextField.rac_textSignal,
RACObserve(LoginManager.sharedManager, loggingIn),
RACObserve(self, loggedIn)
] reduce:^(NSString *username, NSString *password, NSNumber *loggingIn, NSNumber *loggedIn) {
return @(username.length > 0 && password.length > 0 && !loggingIn.boolValue && !loggedIn.boolValue);
}];
[[self.logInButton rac_signalForControlEvents:UIControlEventTouchUpInside] subscribeNext:^(UIButton *sender) {
@strongify(self);
RACSignal *loginSignal = [LoginManager.sharedManager
logInWithUsername:self.usernameTextField.text
password:self.passwordTextField.text];
[loginSignal subscribeError:^(NSError *error) {
@strongify(self);
[self presentError:error];
} completed:^{
@strongify(self);
self.loggedIn = YES;
}];
}];
RAC(self, loggedIn) = [[NSNotificationCenter.defaultCenter
rac_addObserverForName:UserDidLogOutNotification object:nil]
mapReplace:@NO];
Dependencies are most often found in network requests, where a previous request to the server needs to complete before the next one can be constructed, and so on:
ent logInWithSuccess:^{
[client loadCachedMessagesWithSuccess:^(NSArray *messages) {
[client fetchMessagesAfterMessage:messages.lastObject success:^(NSArray *nextMessages) {
NSLog(@"Fetched all messages.");
} failure:^(NSError *error) {
[self presentError:error];
}];
} failure:^(NSError *error) {
[self presentError:error];
}];
ilure:^(NSError *error) {
[self presentError:error];
ReactiveObjC makes this pattern particularly easy:
client logIn]
then:^{
return [client loadCachedMessages];
}]
flattenMap:^(NSArray *messages) {
return [client fetchMessagesAfterMessage:messages.lastObject];
}]
subscribeError:^(NSError *error) {
[self presentError:error];
} completed:^{
NSLog(@"Fetched all messages.");
}];
Working with independent data sets in parallel and then combining them into a final result is non-trivial in Cocoa, and often involves a lot of synchronization:
ock NSArray *databaseObjects;
ock NSArray *fileContents;
erationQueue *backgroundQueue = [[NSOperationQueue alloc] init];
ockOperation *databaseOperation = [NSBlockOperation blockOperationWithBlock:^{
databaseObjects = [databaseClient fetchObjectsMatchingPredicate:predicate];
ockOperation *filesOperation = [NSBlockOperation blockOperationWithBlock:^{
NSMutableArray *filesInProgress = [NSMutableArray array];
for (NSString *path in files) {
[filesInProgress addObject:[NSData dataWithContentsOfFile:path]];
}
fileContents = [filesInProgress copy];
ockOperation *finishOperation = [NSBlockOperation blockOperationWithBlock:^{
[self finishProcessingDatabaseObjects:databaseObjects fileContents:fileContents];
NSLog(@"Done processing");
ishOperation addDependency:databaseOperation];
ishOperation addDependency:filesOperation];
kgroundQueue addOperation:databaseOperation];
kgroundQueue addOperation:filesOperation];
kgroundQueue addOperation:finishOperation];
The above code can be cleaned up and optimized by simply composing signals:
ignal *databaseSignal = [[databaseClient
fetchObjectsMatchingPredicate:predicate]
subscribeOn:[RACScheduler scheduler]];
ignal *fileSignal = [RACSignal startEagerlyWithScheduler:[RACScheduler scheduler] block:^(id<RACSubscriber> subscriber) {
NSMutableArray *filesInProgress = [NSMutableArray array];
for (NSString *path in files) {
[filesInProgress addObject:[NSData dataWithContentsOfFile:path]];
}
[subscriber sendNext:[filesInProgress copy]];
[subscriber sendCompleted];
CSignal
combineLatest:@[ databaseSignal, fileSignal ]
reduce:^ id (NSArray *databaseObjects, NSArray *fileContents) {
[self finishProcessingDatabaseObjects:databaseObjects fileContents:fileContents];
return nil;
}]
subscribeCompleted:^{
NSLog(@"Done processing");
}];
Higher-order functions like map, filter, fold/reduce are sorely missing
from Foundation, leading to loop-focused code like this:
tableArray *results = [NSMutableArray array];
(NSString *str in strings) {
if (str.length < 2) {
continue;
}
NSString *newString = [str stringByAppendingString:@"foobar"];
[results addObject:newString];
RACSequence allows any Cocoa collection to be manipulated in a uniform and declarative way:
equence *results = [[strings.rac_sequence
filter:^ BOOL (NSString *str) {
return str.length >= 2;
}]
map:^(NSString *str) {
return [str stringByAppendingString:@"foobar"];
}];
ReactiveObjC supports OS X 10.8+ and iOS 8.0+.
To add RAC to your application:
git submodule update --init --recursive from within the ReactiveObjC folder.ReactiveObjC.xcodeproj into your
application's Xcode project or workspace.ReactiveObjC.framework. RAC must also be added to any
“Copy Frameworks” build phase. If you don't already have one, simply add
a “Copy Files” build phase and target the “Frameworks” destination."$(BUILD_ROOT)/../IntermediateBuildFilesPath/UninstalledProducts/include"
$(inherited) to the “Header Search Paths” build setting (this is only
necessary for archive builds, but it has no negative effect otherwise).-ObjC to the “Other Linker Flags” build setting.To see a project already set up with RAC, check out C-41 or GroceryList, which are real iOS apps written using ReactiveObjC.
ReactiveObjC is inspired by .NET's Reactive Extensions (Rx). Most of the principles of Rx apply to RAC as well. There are some really good Rx resources out there:
RAC and Rx are both frameworks inspired by functional reactive programming. Here are some resources related to FRP: