ReactiveCocoa self-description: working principle and application

ReactiveCocoa (RAC) is an Objective-C framework inspired by functional reactive programming.

If you are already familiar with functional reactive programming or know some of the basic premises of ReactiveCocoa, check out the Documentation folder for an overview of the framework, which contains some in-depth information about how it works.

What is ReactiveCocoa?

The ReactiveCocoa documentation is well written and covers in detail what RAC is and how it works.

If you want to learn a little more, we recommend these resources:

Introduction

When to use ReactiveCocoa

Framework Overview

Basic Operators

Header documentation

Previously answered Stack Overflow questions and GitHub issues

The rest of the Documentation folder

Functional Reactive Programming on iOS(eBook)

If you have any other questions, feel free to file an issue.

file an issue.

introduce

ReactiveCocoa is inspired by functional responsive programming. Rather than using mutable variables which are replaced and modified in-place, RAC provides signals (expressed as RACSignal) to capture current and future values.

By connecting, binding, and responding to signals, software can be written without having to continually observe and update values.

For example, a text field can be bound to its latest state even as it changes, without having to write extra code to update the text field’s state every second. It’s a bit like KVO, but it uses blocks instead of overriding -observeValueForKeyPath:ofObject:change:context:.

Signals can also represent asynchronous operations, a bit like futures and promises. This greatly simplifies asynchronous software, including network processing code.

One of the main advantages of RAC is that it provides a single, unified approach to handling asynchronous behavior, including delegate methods, blocks callbacks, target-action mechanisms, notifications, and KVO.

Here is a simple example:

 // When self.username changes, logs the new name to the console.  
 //  
 // RACObserve(self, username) creates a new RACSignal that sends the current  
 // value of self.username, then the new value whenever it changes.  
 // -subscribeNext: will execute the block whenever the signal sends a value.  
 [RACObserve(self, username) subscribeNext:^(NSString *newName) {
 NSLog(@ "%@" , newName);
 }];

Unlike KVO notifications, signals can be chained together and can operate simultaneously:

 // Only logs names that starts with "j".  
 //  
 // -filter returns a new RACSignal that only sends a new value when its block  
 // returns YES.  
 [[RACObserve(self, username)
 filter:^(NSString *newName) {
 return [newName hasPrefix:@ "j" ];
 }]
 subscribeNext:^(NSString *newName) {
 NSLog(@ "%@" , newName);
 }];

Signals can also be used to expose state. Instead of observing properties or setting other properties to reflect new values, RAC makes it possible to express properties through signals and operations :

 // Creates a one-way binding so that self.createEnabled will be  
 // true whenever self.password and self.passwordConfirmation  
 // are equal.  
 //  
 // RAC() is a macro that makes the binding look nicer.  
 //  
 // +combineLatest:reduce: takes an array of signals, executes the block with the  
 // latest value from each signal whenever any of them changes, and returns a new  
 // RACSignal that sends the return value of that block as values.  
 RAC(self, createEnabled) = [RACSignal
 combineLatest:@[ RACObserve(self, password), RACObserve(self, passwordConfirmation) ]
 reduce:^(NSString *password, NSString *passwordConfirm) {
 return @([passwordConfirm isEqualToString:password]);
 }];

Signals can be used in many places besides KVO. For example, they can also display button presses:

 // Logs a message whenever the button is pressed.  
 //  
 // RACCommand creates signals to represent UI actions. Each signal can  
 // represent a button press, for example, and have additional work associated  
 // with it.  
 //  
 // -rac_command is an addition to NSButton. The button will send itself on that  
 // command whenever it's pressed.  
 self.button.rac_command = [[RACCommand alloc] initWithSignalBlock:^(id _) {
 NSLog(@ "button was pressed!" );
 return [RACSignal empty];
 }];

Or asynchronous network operations:

 // Hooks up a "Log in" button to log in over the network.  
 //  
 // This block will be run whenever the login command is executed, starting  
 // the login process.  
 self.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  
 // the above block, one for each time the command is executed.  
 [self.loginCommand.executionSignals subscribeNext:^(RACSignal *loginSignal) {
 // Log a message whenever we log in successfully.  
 [loginSignal subscribeCompleted:^{
 NSLog(@ "Logged in successfully!" );
 }];
 }];
 // Executes the login command when the button is pressed.  
 self.loginButton.rac_command = self.loginCommand;

Signals can display timers, other UI events, or anything else related to time changes.

For asynchronous operations using signals, more complex behaviors can be achieved by connecting and changing these signals. Work can be simply triggered when a set of operations completes:

 // Performs 2 network operations and logs a message to the console when they are  
 // both completed.  
 //  
 // +merge: takes an array of signals and returns a new RACSignal that passes  
 // through the values ​​of all of the signals and completes when all of the  
 // signals complete.  
 //  
 // -subscribeCompleted: will execute the block when the signal completes.  
 [[RACSignal
 merge:@[ [client fetchUserRepos], [client fetchOrgRepos] ]]
 subscribeCompleted:^{
 NSLog(@ "They're both done!" );
 }];

Signals can execute asynchronous operations sequentially instead of nested block callbacks. This is very similar to futures and promises:

 // Logs in the user, then loads any cached messages, then fetches the remaining  
 // messages from the server. After that's all done, logs a message to the  
 // console.  
 //  
 // The hypothetical -logInUser methods returns a signal that completes after  
 // logging in.  
 //  
 // -flattenMap: will execute its block whenever the signal sends a value, and  
 // returns a new RACSignal that merges all of the signals returned from the block  
 // into 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 can also easily bind the results of asynchronous operations:

 // Creates a one-way binding so that self.imageView.image will be set as the user's  
 // avatar as soon as it's downloaded.  
 //  
 // The hypothetical -fetchUserWithUsername: method returns a signal which sends  
 // the user.  
 //  
 // -deliverOn: creates new signals that will do their work on other queues. In  
 // this 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  
 // RACSignal that sends values ​​returned from the block.  
 RAC(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];

This only describes what RAC can do, but it is difficult to explain why RAC is so powerful. Although it is difficult to explain RAC through this README, I will try to use less code, fewer templates, and better code to express it clearly.

If you want more sample code, check out C-41 or GroceryList, which are real iOS apps written with ReactiveCocoa. For more information about RAC, see the Documentation folder.

When to use ReactiveCocoa

At first glance, ReactiveCocoa is very abstract, and it might be hard to understand how to apply it to a specific problem.

Here are some common places where RAC is used.

Handling asynchronous or event-driven data sources

A lot of Cocoa programming focuses on responding to user events or changing application state. Writing code this way can quickly become a spaghetti-like mess with lots of callbacks and state variables.

This pattern looks different on the surface, like UI callbacks, network responses, and KVO notifications, but actually has a lot in common. RACSignal unifies these APIs so that they can be combined and operated in the same way.

Take the following code as an example:

 static   void *ObservationContext = &ObservationContext;
 - ( void )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];
 }
 - ( void )dealloc {
 [LoginManager.sharedManager removeObserver:self forKeyPath:@ "loggingIn" context:ObservationContext];
 [NSNotificationCenter.defaultCenter removeObserver:self];
 }
 - ( void )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;
 }
 - (IBAction)logInPressed:(UIButton *)sender {
 [[LoginManager sharedManager]
 logInWithUsername:self.usernameTextField.text
 password:self.passwordTextField.text
 success:^{
 self.loggedIn = YES;
 } failure:^(NSError *error) {
 [self presentError:error];
 }];
 }
 - ( void )loggedOut:(NSNotification *)notification {
 self.loggedIn = NO;
 }
 - ( void )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];
 }
 }

…expressed in RAC like this:

 - ( void )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 ];
 }

Connection-dependent operations

Dependencies are often used in network requests. When the next network request to the server needs to be built after the previous one is completed, you can look at the following code:

 [client 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];
 }];
 } failure:^(NSError *error) {
 [self presentError:error];
 }];

ReactiveCocoa makes this pattern particularly easy:

 __block NSArray *databaseObjects;
 __block NSArray *fileContents;
 NSOperationQueue *backgroundQueue = [[NSOperationQueue alloc] init];
 NSBlockOperation *databaseOperation = [NSBlockOperation blockOperationWithBlock:^{
 databaseObjects = [databaseClient fetchObjectsMatchingPredicate:predicate];
 }];
 NSBlockOperation *filesOperation = [NSBlockOperation blockOperationWithBlock:^{
 NSMutableArray *filesInProgress = [NSMutableArray array];
 for (NSString *path in files) {
 [filesInProgress addObject:[NSData dataWithContentsOfFile:path]];
 }
 fileContents = [filesInProgress copy];
 }];
 NSBlockOperation *finishOperation = [NSBlockOperation blockOperationWithBlock:^{
 [self finishProcessingDatabaseObjects:databaseObjects fileContents:fileContents];
 NSLog(@ "Done processing" );
 }];
 [finishOperation addDependency:databaseOperation];
 [finishOperation addDependency:filesOperation];
 [backgroundQueue addOperation:databaseOperation];
 [backgroundQueue addOperation:filesOperation];
 [backgroundQueue addOperation:finishOperation];

The above code can be easily cleaned up and optimized using synthetic signals:

 RACSignal *databaseSignal = [[databaseClient
 fetchObjectsMatchingPredicate:predicate]
 subscribeOn:[RACScheduler scheduler]];
 RACSignal *fileSignal = [RACSignal startEagerlyWithScheduler:[RACScheduler scheduler] block:^(id subscriber) {
 NSMutableArray *filesInProgress = [NSMutableArray array];
 for (NSString *path in files) {
 [filesInProgress addObject:[NSData dataWithContentsOfFile:path]];
 }
 [subscriber sendNext:[filesInProgress copy]];
 [subscriber sendCompleted];
 }];
 [[RACSignal
 combineLatest:@[ databaseSignal, fileSignal ]
 reduce:^ id (NSArray *databaseObjects, NSArray *fileContents) {
 [self finishProcessingDatabaseObjects:databaseObjects fileContents:fileContents];
 return nil;
 }]
 subscribeCompleted:^{
 NSLog(@ "Done processing" );
 }];

Simplifying collection conversions

Advanced features like map, filter, fold/reduce are sorely lacking in Foundation, leading to loop-heavy code like this:

 NSMutableArray *results = [NSMutableArray array];
 for (NSString *str in strings) {
 if (str.length < 2 ) {
 continue ;
 }
 NSString *newString = [str stringByAppendingString:@ "foobar" ];
 [results addObject:newString];
 }

RACSequence allows Cocoa collections to be manipulated in a unified way:

 RACSequence *results = [[strings.rac_sequence
 filter:^ BOOL (NSString *str) {
 return str.length >= 2 ;
 }]
 map:^(NSString *str) {
 return [str stringByAppendingString:@ "foobar" ];
 }];

System requirements

ReactiveCocoa requires OS X 10.8+ and iOS 8.0+.

Introducing ReactiveCocoa

To add RAC to your application:

1. Add the ReactiveCocoa repository as a submodule of your application repository.

2. Run script/bootstrap from the ReactiveCocoa folder.

3. Drag ReactiveCocoa.xcodeproj into your app’s Xcode project or workspace.

4. In the "Build Phases" tab of your application target, add RAC to "Link Binary With Libraries"

On iOS, add libReactiveCocoa-iOS.a.

On OS X, add ReactiveCocoa.framework.

RAC must select "Copy Frameworks". If you don't have it, you need to select "Copy Files" and "Frameworks".

5. Add "$(BUILD_ROOT)/../IntermediateBuildFilesPath/UninstalledProducts/include"

$(inherited) to "Header Search Paths" (this requires archive builds, but has no effect).

6. For iOS targets, add -ObjC to "Other Linker Flags" .

7. If you add RAC to a project (not a workspace), you need to add the appropriate RAC target to your application's "Target Dependencies".

If you prefer to use CocoaPods, there are some generous third-party contributed ReactiveCocoa podspecs.

To see a project using RAC, check out C-41 or GroceryList, which are real iOS apps written with ReactiveCocoa.

Independent development

If you are working with RAC in isolation rather than integrating it into another project, you will want to open ReactiveCocoa.xcworkspace instead of .xcodeproj.

More information

ReactiveCocoa is inspired by .NET's ReactiveExtensions (Rx). Some of the principles of Rx can also be used well in RAC. Here are some good Rx resources:

Reactive Extensions MSDN entry

Reactive Extensions for .NET Introduction

Rx - Channel 9 videos

Reactive Extensions wiki

101 Rx Samples

Programming Reactive Extensions and LINQ

RAC and Rx are both inspired by functional reactive programming. Here are some resources about FRP:

What is FRP? - Elm Language

What is Functional Reactive Programming - Stack Overflow

Specification for a Functional Reactive Language - Stack Overflow

Escape from Callback Hell

Principles of Reactive Programming on Coursera