a\nview controller manages a screenful of content.\nThis has since changed to
a view controller manages a self-contained\nunit of content.\nWhy didn't Apple want us to build our own tab bar controllers and\nnavigation controllers? Or put more precisely, what is the problem with: \n\n```objc\n[viewControllerA.view addSubView:viewControllerB.view]\n```\n\n\n\nThe UIWindow, which serves as an app's root view, is where rotation and\ninitial layout messages originate from. In the\nillustration above, the child view controller, whose view was inserted\nin the root view controller view hierarchy, is excluded from those events.\nView event methods like `viewWillAppear:` will not get called.\n\nThe custom view controller containers built before iOS 5 would keep a\nreference to the child view controllers and manually relay all the\nview event methods called on the parent view controller, which is\npretty difficult to get right.\n\n## An Example\n\nWhen you were a kid playing in the sand, did your parents ever tell you that if you kept digging with your little shovel you would end up in China?\nMine did, and I made a small demo app called *Tunnel* to test this claim. \nYou can clone the [GitHub\nrepo](https://github.com/objcio/issue-1-view-controller-containment) and run the\napp, which will make it easier to understand the example code.\n*(Spoiler: digging through the earth from western Denmark lands you somewhere in the South Pacific Ocean.)*\n\n\n\nTo find the antipode, as the opposite location is called, move the little guy with the shovel around and the map will tell you where your exit location is. Tap the radar button and the map will flip to reveal the name of the location.\n\nThere are two map view controllers on screen. Each of them has to deal with dragging, annotation, and updating the map.\nFlipping these over reveals two new view controllers which reverse geocode the locations.\nAll the view controllers are contained inside a parent view controller, which holds their views, and ensures that layout and rotation behaves as expected.\n\nThe root view controller has two container views. These are added to\nmake it easier to layout and animate the views of child view\ncontrollers, as we will see later on.\n\n```objc\n- (void)viewDidLoad\n{\n [super viewDidLoad];\n\n //Setup controllers\n _startMapViewController = [RGMapViewController new];\n [_startMapViewController setAnnotationImagePath:@\"man\"];\n [self addChildViewController:_startMapViewController]; // 1\n [topContainer addSubview:_startMapViewController.view]; // 2\n [_startMapViewController didMoveToParentViewController:self]; // 3\n [_startMapViewController addObserver:self\n forKeyPath:@\"currentLocation\" \n options:NSKeyValueObservingOptionNew \n context:NULL];\n\n _startGeoViewController = [RGGeoInfoViewController new]; // 4\n}\n```\n\nThe `_startMapViewController`, which displays the starting position, is instantiated and set up with the annotation image.\n\n1. The `_startMapViewController` is added as a child of the root view\n controller. This automatically calls\nthe method `willMoveToParentViewController:` on the child.\n2. The child's view is added as a subview of the first container view.\n3. The child is notified that it now has a parent view controller.\n4. The child view controller that does the geocoding is instantiated,\n but not inserted in any view or controller hierarchy yet.\n\n\n\n## Layout\n\nThe root view controller defines the two container views,\nwhich determine the size of the child view controllers.\nThe child view controllers do not know which container they will be\nadded to, and therefore have to be flexible in size:\n\n```objc\n- (void) loadView\n{\n mapView = [MKMapView new];\n mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth |UIViewAutoresizingFlexibleHeight;\n [mapView setDelegate:self];\n [mapView setMapType:MKMapTypeHybrid];\n\n self.view = mapView;\n}\n```\n\nNow they will layout using the bounds of their super view. This increases the reusability of the child view controller; if we were to push it on the stack of a navigation controller, it would still layout correctly.\n\n## Transitions\n\nApple has made the view controller containment API so fine-grained that\nit is possible to construct and animate any containment scenario we can\nthink of.\nApple also provides a block-based convenience method for exchanging two controller views on the screen.\nThe method\n`transitionFromViewController:toViewController:(...)`\ntakes care of a lot of the details for us: \n\n```objc\n- (void) flipFromViewController:(UIViewController*) fromController \n toViewController:(UIViewController*) toController \n withDirection:(UIViewAnimationOptions) direction\n{\n toController.view.frame = fromController.view.bounds; // 1\n [self addChildViewController:toController]; // \n [fromController willMoveToParentViewController:nil]; // \n \n [self transitionFromViewController:fromController\n toViewController:toController\n duration:0.2\n options:direction | UIViewAnimationOptionCurveEaseIn\n animations:nil\n completion:^(BOOL finished) {\n \n [toController didMoveToParentViewController:self]; // 2\n [fromController removeFromParentViewController]; // 3\n }];\n}\n```\n\n1. Before the animation we add the `toController` as a child and we\n inform the `fromController` that it will be removed. If the fromController's view is part of the container's view hierarchy, this is where `viewWillDisappear:` is called.\n2. `toController` is informed of its new parent, and appropriate view\n event methods will be called.\n3. The `fromController` is removed.\n\nThis convenience method for view controller transitions automatically swaps out the old view controller's view for the new one. However, if you implement your own transition and you wish to only display one view at a time, you have to call `removeFromSuperview` on the old view and `addSubview:` for the new view yourself. Getting the sequence of method calls wrong will most likely result in an `UIViewControllerHierarchyInconsistency` warning. For example, this will\nhappen if you call `didMoveToParentViewController:` before you added the view.\n\nIn order to be able to use the `UIViewAnimationOptionTransitionFlipFromTop` animation, we had to add the children's views to our view containers instead of to the root view controller's view. Otherwise the animation would result in the entire root view flipping over.\n\n\n## Communication\n\nView controllers should be reusable and self-contained entities. Child view controllers are no exception to this rule of thumb. In order to achieve this, the parent view controller should only be concerned with two tasks: laying out the child view controller's root view, and communicating with the child view controller through its exposed API. It should never modify the child's view tree or other internal state directly.\n\nChild view controllers should contain the necessary logic to manage their view trees themselves -- don't treat them as dumb views. This will result in a clearer separation of concerns and better reusability.\n\nIn the Tunnel example app, the parent view controller observes a property called `currentLocation` on the map view controllers:\n\n```objc\n[_startMapViewController addObserver:self \n forKeyPath:@\"currentLocation\"\n options:NSKeyValueObservingOptionNew\n context:NULL];\n```\n\nWhen this property changes in response to moving the little guy with the shovel around on the map, the parent view controller communicates the antipode of the new location to the other map:\n\n```objc\n[oppositeController updateAnnotationLocation:[newLocation antipode]];\n```\n\n\nLikewise, when you tap the radar button, the parent view controller sets the locations to be reverse geocoded on the new child view controllers: \n\n```objc\n[_startGeoViewController setLocation:_startMapViewController.currentLocation];\n[_targetGeoViewController setLocation:_targetMapViewController.currentLocation];\n```\n\nIndependent of the technique you choose to communicate from child to parent view controllers (KVO, notifications, or the delegate pattern), the goal always stays the same: the child view controllers should be independent and reusable. In our example we could push one of the child view controllers on a navigation stack, but the communication would still work through the same API. \n" }, { "path": "2013-06-07-introduction.markdown", "content": "---\ntitle: \"Introduction\"\ncategory: \"1\"\ndate: \"2013-06-07 12:00\"\ntags: editorial\n---\n\nWelcome to the first edition of objc.io, a periodical about best practices and advanced techniques in Objective-C!\n\nobjc.io was founded in Berlin by [Chris Eidhof](https://twitter.com/chriseidhof), [Daniel Eggert](https://twitter.com/danielboedewadt), and [Florian Kugler](https://twitter.com/floriankugler). We started objc.io to create a regular platform for in-depth technical topics relevant to all iOS and OS X developers.\n\nEach edition of objc.io has a focus on one particular subject, with multiple articles covering different aspects of that topic. The subject of this first edition is *Lighter View Controllers*, and it contains four articles – three from the founding team and one from [Ricki Gregersen](https://twitter.com/rickigregersen), whom we would like to welcome as our first guest writer! \n\nIt's a common problem in the code base of iOS apps that view controllers get out of hand, because they do too much. By factoring out reusable code, they are easier to understand, easier to maintain and easier to test. This issue will focus on best practices and techniques how you can keep view controllers clean.\n\nWe will look at how to make view controllers primarily coordinating objects by factoring out view and model code, as well as introducing other controller objects in addition to view controllers. Furthermore, we will look at splitting up view controllers using the view controller containment mechanism, and finally, discuss how to test clean view controllers.\n\nIn upcoming editions we will have more articles from great guest writers of the Objective-C community; [Loren Brichter](https://twitter.com/lorenb), [Peter Steinberger](https://twitter.com/steipete), [Brent Simmons](https://twitter.com/brentsimmons), and [Ole Begemann](https://twitter.com/olebegemann) have committed to writing in the future. [Contact us](mailto:mail@objc.io) if you have an idea for an interesting topic and you would like to contribute an article about it to objc.io.\n\nChris, Daniel, and Florian.\n" }, { "path": "2013-06-07-lighter-view-controllers.md", "content": "---\ntitle: \"Lighter View Controllers\"\ncategory: \"1\"\ndate: \"2013-06-07 11:00:00\"\nauthor:\n - name: Chris Eidhof\n url: http://twitter.com/chriseidhof\ntags: article\n---\n\nView controllers are often the biggest files in iOS\nprojects, and they often contain way more code than necessary. Almost always,\nview controllers are the least reusable part of the code. We will look\nat techniques to slim down your view controllers, make code reusable, and move code to more appropriate places.\n\nThe [example project](https://github.com/objcio/issue-1-lighter-view-controllers) for this issue is on GitHub.\n\n## Separate Out Data Source and Other Protocols\n\nOne of the most powerful techniques to slim down your view controller is\nto take the `UITableViewDataSource` part of your code, and move it to\nits own class. If you do this more than once, you will start to see\npatterns and create reusable classes for this.\n\nFor example, in our example project, there is a class\n`PhotosViewController` which had the following methods:\n\n```objc\n# pragma mark Pragma \n\n- (Photo*)photoAtIndexPath:(NSIndexPath*)indexPath {\n return photos[(NSUInteger)indexPath.row];\n}\n\n- (NSInteger)tableView:(UITableView*)tableView \n numberOfRowsInSection:(NSInteger)section {\n return photos.count;\n}\n\n- (UITableViewCell*)tableView:(UITableView*)tableView \n cellForRowAtIndexPath:(NSIndexPath*)indexPath {\n PhotoCell* cell = [tableView dequeueReusableCellWithIdentifier:PhotoCellIdentifier \n forIndexPath:indexPath];\n Photo* photo = [self photoAtIndexPath:indexPath];\n cell.label.text = photo.name;\n return cell;\n}\n```\n\n\n \nA lot of this code has to do with arrays, and some of it is\nspecific to the photos that the view controller manages. So let's try to move the array-related code into its [own\nclass](https://github.com/objcio/issue-1-lighter-view-controllers/blob/master/PhotoData/ArrayDataSource.h).\nWe use a block for configuring the cell, but it might as well be\na delegate, depending on your use-case and taste.\n\n```objc\n@implementation ArrayDataSource\n\n- (id)itemAtIndexPath:(NSIndexPath*)indexPath {\n return items[(NSUInteger)indexPath.row];\n}\n\n- (NSInteger)tableView:(UITableView*)tableView \n numberOfRowsInSection:(NSInteger)section {\n return items.count;\n}\n\n- (UITableViewCell*)tableView:(UITableView*)tableView \n cellForRowAtIndexPath:(NSIndexPath*)indexPath {\n id cell = [tableView dequeueReusableCellWithIdentifier:cellIdentifier\n forIndexPath:indexPath];\n id item = [self itemAtIndexPath:indexPath];\n configureCellBlock(cell,item);\n return cell;\n}\n\n@end\n```\n\nThe three methods that were in your view controller can go, and instead\nyou can create an instance of this object and set it as the table view's\ndata source.\n\n```objc\nvoid (^configureCell)(PhotoCell*, Photo*) = ^(PhotoCell* cell, Photo* photo) {\n cell.label.text = photo.name;\n};\nphotosArrayDataSource = [[ArrayDataSource alloc] initWithItems:photos\n cellIdentifier:PhotoCellIdentifier\n configureCellBlock:configureCell];\nself.tableView.dataSource = photosArrayDataSource;\n```\n\nNow you don't have to worry about mapping an index path to a\nposition in the array, and every time you want to display an\narray in a table view you can reuse this code. You can also implement\nadditional methods such as\n`tableView:commitEditingStyle:forRowAtIndexPath:` and share that code among\nall your table view controllers.\n\nThe nice thing is that we can [test this class](/issues/1-view-controllers/testing-view-controllers/#testing-a-data-source) separately,\nand never have to worry about writing it again. The same principle\napplies if you use something else other than arrays.\n\nIn one of the applications we were working on this year,\nwe made heavy use of Core Data. We created a similar class, but instead\nof being backed by an array, it is backed by a\nfetched results controller. It implements all the logic for\nanimating the updates, doing section headers, and deletion. You can\nthen create an instance of this object and feed it a fetch request and a\nblock for configuring the cell, and the rest will be taken care of.\n\nFurthermore, this approach extends to other protocols as well. One\nobvious candidate is `UICollectionViewDataSource`. This gives you\ntremendous flexibility; if, at some point during the development, you\ndecide to have a `UICollectionView` instead of a `UITableView`, you\nhardly have to change anything in your view controller. You could even\nmake your data source support both protocols.\n\n## Move Domain Logic into the Model\n\n\nHere is an example of code in view controller (from another project) that is supposed to find a list of active\npriorities for a user:\n\n```objc\n- (void)loadPriorities {\n NSDate* now = [NSDate date];\n NSString* formatString = @\"startDate <= %@ AND endDate >= %@\";\n NSPredicate* predicate = [NSPredicate predicateWithFormat:formatString, now, now];\n NSSet* priorities = [self.user.priorities filteredSetUsingPredicate:predicate];\n self.priorities = [priorities allObjects];\n}\n```\n\nHowever, it is much cleaner to move this code to a category on the `User` class. Then\nit looks like this in `View Controller.m`:\n\n```objc\n- (void)loadPriorities {\n self.priorities = [self.user currentPriorities];\n}\n```\n\nand in `User+Extensions.m`:\n\n\n```objc\n- (NSArray*)currentPriorities {\n NSDate* now = [NSDate date];\n NSString* formatString = @\"startDate <= %@ AND endDate >= %@\";\n NSPredicate* predicate = [NSPredicate predicateWithFormat:formatString, now, now];\n return [[self.priorities filteredSetUsingPredicate:predicate] allObjects];\n}\n```\n\nSome code cannot be easily moved into a model object but is still\nclearly associated with model code, and for this, we can use a `Store`:\n\n## Creating the Store Class\n\nIn the first version of our example application, we had some code to\nload data from a file and parse it. This code was in the view\ncontroller:\n\n```objc\n- (void)readArchive {\n NSBundle* bundle = [NSBundle bundleForClass:[self class]];\n NSURL *archiveURL = [bundle URLForResource:@\"photodata\"\n withExtension:@\"bin\"];\n NSAssert(archiveURL != nil, @\"Unable to find archive in bundle.\");\n NSData *data = [NSData dataWithContentsOfURL:archiveURL\n options:0\n error:NULL];\n NSKeyedUnarchiver *unarchiver = [[NSKeyedUnarchiver alloc] initForReadingWithData:data];\n _users = [unarchiver decodeObjectOfClass:[NSArray class] forKey:@\"users\"];\n _photos = [unarchiver decodeObjectOfClass:[NSArray class] forKey:@\"photos\"];\n [unarchiver finishDecoding];\n}\n```\n\nThe view controller should not have to know about this.\nWe created a *Store* object that does just this. By separating it\nout, we can reuse that code, test it separately and keep our view\ncontroller small. The store can take care of data loading, caching,\nand setting up the database stack. This store is also often called a\n*service layer* or a *repository*. \n\n\n## Move Web Service Logic to the Model Layer\n\nThis is very similar to the topic above: don't do web service logic in\nyour view controller. Instead, encapsulate this in a different class.\nYour view controller can then call methods on this class with a callback\nhandler (for example, a completion block).\nThe nice thing is that you can do all your caching and error handling in\nthis class too.\n\n## Move View Code into the View Layer\n\nBuilding complicated view hierarchies shouldn't be done in view\ncontrollers. Either use interface builder, or encapsulate views into\ntheir own `UIView` subclasses. For example, if you build your own date\npicker control, it makes more sense to put this into a\n`DatePickerView` class than creating the whole thing in the view\ncontroller. Again, this increases reusability and simplicity.\n\nIf you like Interface Builder, then you can also do this in\nInterface Builder. Some people assume you can only use this for view\ncontrollers, but you can also load separate nib files with your custom\nviews. In our example app, we created a [`PhotoCell.xib`](https://github.com/objcio/issue-1-lighter-view-controllers/blob/master/PhotoData/PhotoCell.xib) that\ncontains the layout for a photo cell:\n\n \n\nAs you can see, we created properties on the view (we don't use the\nFile's Owner object in this xib) and connect them to specific subviews.\nThis technique is also very handy for other custom views.\n \n## Communication\n\nOne of the other things that happen a lot in view controllers is\ncommunication with other view controllers, the model, and the views.\nWhile this is exactly what a controller should do, it is also something\nwe'd like to achieve with as minimal code as possible.\n\nThere are a lot of well-explained techniques for communication between\nyour view controllers and your model objects (such as KVO and fetched\nresults controllers), however, communication between view controllers is\noften a bit less clear. \n\nWe often have the problem where one view controller has some state and\ncommunicates with multiple other view controllers. Often, it then makes\nsense to put this state into a separate object and pass it around the\nview controllers, which then all observe and modify that state. The\nadvantage is that it's all in one place, and we don't end up entangled\nin nested delegate callbacks. This is a complex subject, and we might\ndedicate a whole issue to this in the future.\n\n## Conclusion\n\nWe've seen some techniques for creating smaller view controllers. We\ndon't strive to apply these techniques wherever possible, as we have only\none goal: to write maintainable code. By knowing these patterns, we have better\nchances of taking unwieldy view controllers and making them clearer.\n\n### Further Reading\n\n* [View Controller Programming Guide for iOS](http://developer.apple.com/library/ios/#featuredarticles/ViewControllerPGforiPhoneOS/BasicViewControllers/BasicViewControllers.html)\n* [Cocoa Core Competencies: Controller Object](http://developer.apple.com/library/mac/#documentation/General/Conceptual/DevPedia-CocoaCore/ControllerObject.html)\n* [Writing high quality view controllers](http://subjective-objective-c.blogspot.de/2011/08/writing-high-quality-view-controller.html)\n* [Programmers Stack Exchange: Model View Controller Store](http://programmers.stackexchange.com/questions/184396/mvcs-model-view-controller-store)\n* [Unburdened View Controllers](https://speakerdeck.com/trianglecocoa/unburdened-viewcontrollers-by-jay-thrash)\n* [Programmers Stack Exchange: How to avoid big and clumsy `UITableViewControllers` on iOS](http://programmers.stackexchange.com/questions/177668/how-to-avoid-big-and-clumsy-uitableviewcontroller-on-ios)\n\n" }, { "path": "2013-06-07-table-views.md", "content": "---\ntitle: \"Clean Table View Code\"\ncategory: \"1\"\ndate: \"2013-06-07 10:00:00\"\nauthor:\n - name: Florian Kugler\n url: http://twitter.com/floriankugler\ntags: article\n---\n\nTable views are an extremely versatile building block for iOS apps. Therefore, a lot of code is directly or indirectly related to table view tasks, including supplying data, updating the table view, controlling its behavior, and reacting to selections, to name just a few. In this article, we will present techniques to keep this code clean and well-structured. \n\n## UITableViewController vs. UIViewController\n\nApple provides `UITableViewController` as dedicated view controller class for table views. Table view controllers implement a handful of very useful features which can help you to avoid writing the same boilerplate code over and over. On the flip side, table view controllers are restricted to managing exactly one table view, which is presented full screen. However, in many cases, this is all you need, and if it's not, there are ways to work around this, as we will show below.\n\n### Features of Table View Controllers\n\nTable view controllers help you with loading the table view's data\nwhen it is shown for the first time. More specifically, it helps with toggling the table view's\nediting mode, with reacting to the keyboard notifications, and\nwith a few small tasks like flashing the scroll indicator and clearing\nthe selection. In order for these features to work, it is important that\nyou call super on any view event methods (such as `viewWillAppear:` and `viewDidAppear:`) that you may override in your custom subclass.\n\nTable view controllers have one unique selling point over standard view controllers, and that's the support for Apple's implementation for \"pull to refresh.\" At the moment, the only documented way of using `UIRefreshControl` is within a table view controller. There are ways to make it work in other contexts, but these could easily not work with the next iOS update.\n\nThe sum of all these elements provides much of the standard table view interface behavior as Apple has defined it. If your app conforms to these standards, it is a good idea to stick with table view controllers in order to avoid writing boilerplate code.\n\n### Limitations of Table View Controllers\n\nThe view property of table view controllers always has to be set to a table view. If you decide later on that you want to show something else on the screen aside from the table view (e.g. a map), you are out of luck if you don't want to rely on awkward hacks. \n\nIf you have defined your interface in code or using a .xib file, then it is pretty easy to transition to a standard view controller. If you're using storyboards, then this process involves a few more steps. With storyboards, you cannot change a table view controller to a standard view controller without recreating it. This means you have to copy all the contents over to the new view controller and wire everything up again.\n\nFinally, you need to add back the features of table view controller that you lost in this transition. Most of them are simple single-line statements in `viewWillAppear` or `viewDidAppear`. Toggling the editing state requires implementing an action method which flips the table view's `editing` property. The most work lies in recreating the keyboard support.\n\nBefore you go down this route though, here is an easy alternative that has the additional benefit of separating concerns:\n\n### Child View Controllers\n\nInstead of getting rid of the table view controller entirely, you could\nalso add it as a child view controller to another view controller (see\nthe [article about view controller containment](/issues/1-view-controllers/containment-view-controller/) in this issue). Then the table view controller continues to manage only the table view and the parent view controller can take care of whatever additional interface elements you might need. \n\n \n```objc\n- (void)addPhotoDetailsTableView\n{\n DetailsViewController *details = [[DetailsViewController alloc] init];\n details.photo = self.photo;\n details.delegate = self;\n [self addChildViewController:details];\n CGRect frame = self.view.bounds;\n frame.origin.y = 110;\n details.view.frame = frame;\n [self.view addSubview:details.view]; \n [details didMoveToParentViewController:self];\n}\n```\n\nIf you use this solution you have to create a communication channel from\nthe child to the parent view controller. For example, if the user selects a cell in the table view, the parent view controller needs to know about this in order to push another view controller. Depending on the use case, often the cleanest way to do this is to define a delegate protocol for the table view controller, which you then implement on the parent view controller. \n\n```objc\n@protocol DetailsViewControllerDelegate\n- (void)didSelectPhotoAttributeWithKey:(NSString *)key;\n@end\n\n@interface PhotoViewController ()
If you always read or write a file’s contents from start to\nfinish, streams provide a simple interface for doing so\nasynchronously..\n\nWhether you use streams or not, the general pattern for reading a file\nline-by-line is as follows:\n\n1. Have an intermediate buffer that you append to while not finding a newline\n2. Read a chunk from the stream\n3. For each newline found in the chunk, take the intermediate buffer,\n append data from the stream up to (and including) the newline, and output that\n4. Append the remaining bytes to the intermediate buffer\n5. Go back to 2 until the stream closes\n\nTo put this into practice, we created a [sample application](https://github.com/objcio/issue-2-background-file-io) with a\n`Reader` class that does just this. The interface is very simple:\n\n```objc\n@interface Reader : NSObject\n- (void)enumerateLines:(void (^)(NSString*))block\n completion:(void (^)())completion;\n- (id)initWithFileAtPath:(NSString*)path;\n@end\n```\n\nNote that this is not a subclass of `NSOperation`. Like URL connections, \ninput streams deliver\ntheir events using a run loop. Therefore, we will use the main run loop \nagain for event delivery, and then dispatch the processing of the data\nonto a background operation queue.\n\n```objc\n- (void)enumerateLines:(void (^)(NSString*))block\n completion:(void (^)())completion\n{\n if (self.queue == nil) {\n self.queue = [[NSOperationQueue alloc] init];\n self.queue.maxConcurrentOperationCount = 1;\n }\n self.callback = block;\n self.completion = completion;\n self.inputStream = [NSInputStream inputStreamWithURL:self.fileURL];\n self.inputStream.delegate = self;\n [self.inputStream scheduleInRunLoop:[NSRunLoop currentRunLoop]\n forMode:NSDefaultRunLoopMode];\n [self.inputStream open];\n}\n```\n\nNow the input stream will send us delegate messages (on the main\nthread), and we do the processing on the operation\nqueue by adding a block operation:\n\n```objc\n- (void)stream:(NSStream*)stream handleEvent:(NSStreamEvent)eventCode\n{\n switch (eventCode) {\n ...\n case NSStreamEventHasBytesAvailable: {\n NSMutableData *buffer = [NSMutableData dataWithLength:4 * 1024];\n NSUInteger length = [self.inputStream read:[buffer mutableBytes] \n maxLength:[buffer length]];\n if (0 < length) {\n [buffer setLength:length];\n __weak id weakSelf = self;\n [self.queue addOperationWithBlock:^{\n [weakSelf processDataChunk:buffer];\n }];\n }\n break;\n }\n ...\n }\n}\n```\n\nProcessing a data chunk looks at the current buffered data and appends\nthe newly streamed chunk. It then breaks that into components, separated\nby newlines, and emits each line. The remainder gets stored again:\n\n```objc\n- (void)processDataChunk:(NSMutableData *)buffer;\n{\n if (self.remainder != nil) {\n [self.remainder appendData:buffer];\n } else {\n self.remainder = buffer;\n }\n [self.remainder obj_enumerateComponentsSeparatedBy:self.delimiter\n usingBlock:^(NSData* component, BOOL last) {\n if (!last) {\n [self emitLineWithData:component];\n } else if (0 < [component length]) {\n self.remainder = [component mutableCopy];\n } else {\n self.remainder = nil;\n }\n }];\n}\n```\n\nIf you run the sample app, you will see that the app stays very\nresponsive, and the memory stays very low (in our test runs, the heap\nsize stayed under 800 KB, regardless of the file size). For processing\nlarge files chunk by chunk, this technique is probably what you want.\n\nFurther reading:\n\n* [File System Programming Guide: Techniques for Reading and Writing Files Without File Coordinators](http://developer.apple.com/library/ios/#documentation/FileManagement/Conceptual/FileSystemProgrammingGUide/TechniquesforReadingandWritingCustomFiles/TechniquesforReadingandWritingCustomFiles.html)\n* [StackOverflow: How to read data from NSFileHandle line by line?](http://stackoverflow.com/questions/3707427/how-to-read-data-from-nsfilehandle-line-by-line)\n\n## Conclusion\n\nIn the examples above we demonstrated how to perform common tasks\nasynchronously in the background. In all of these solutions, we tried \nto keep our code simple, because it's very easy to make mistakes with \nconcurrent programming without noticing.\n\nOftentimes you might get away with just doing your work on the main thread,\nand when you can, it'll make your life a lot easier. But if you find performance bottlenecks, put these tasks into the background using the \nsimplest approach possible. \n\nThe pattern we showed in the examples above is a safe choice for other \ntasks as well. Receive events or data on the main queue, then\nuse a background operation queue to perform the actual work before getting \nback onto the main queue to deliver the results.\n\n\n[90]: /issues/2-concurrency/editorial/\n[100]: /issues/2-concurrency/concurrency-apis-and-pitfalls/\n[101]: /issues/2-concurrency/concurrency-apis-and-pitfalls/#challenges\n[102]: /issues/2-concurrency/concurrency-apis-and-pitfalls/#priority_inversion\n[103]: /issues/2-concurrency/concurrency-apis-and-pitfalls/#shared_resources\n[104]: /issues/2-concurrency/concurrency-apis-and-pitfalls/#dead_locks\n[200]: /issues/2-concurrency/common-background-practices/\n[300]: /issues/2-concurrency/low-level-concurrency-apis/\n[301]: /issues/2-concurrency/low-level-concurrency-apis/#async\n[302]: /issues/2-concurrency/low-level-concurrency-apis/#multiple-readers-single-writer\n[400]: /issues/2-concurrency/thread-safe-class-design/\n" }, { "path": "2013-07-07-concurrency-apis-and-pitfalls.md", "content": "---\ntitle: \"Concurrent Programming: APIs and Challenges\"\ncategory: \"2\"\ndate: \"2013-07-07 10:00:00\"\nauthor:\n - name: Florian Kugler\n url: http://twitter.com/floriankugler\ntags: article\n---\n\n\n[Concurrency](http://en.wikipedia.org/wiki/Concurrency_%28computer_science%29) describes the concept of running several tasks at the same time. This can either happen in a [time-shared](http://en.wikipedia.org/wiki/Preemption_%28computing%29) manner on a single CPU core, or truly in parallel if multiple CPU cores are available.\n\nOS X and iOS provide several different APIs to enable concurrent programming. Each of these APIs has different capabilities and limitations, making them suitable for different tasks. They also sit on very different levels of abstraction. We have the possibility to operate very close to the metal, but this also comes with great responsibility to get things right. \n\nConcurrent programming is a very difficult subject with many intricate problems and pitfalls, and it's easy to forget this while using APIs like Grand Central Dispatch or `NSOperationQueue`. This article will first give an overview of the different concurrency APIs on OS X and iOS, and then dive deeper into the inherent challenges of concurrent programming, which are independent of the specific API you use.\n\n\n## Concurrency APIs on OS X and iOS\n\nApple's mobile and desktop operating systems provide the same APIs for concurrent programming. In this article we are going to take a look at `pthread` and `NSThread`, Grand Central Dispatch, `NSOperationQueue`, and `NSRunLoop`. Technically, run loops are the odd ones out in this list, because they don't enable true parallelism. But they are related closely enough to the topic that it's worth having a closer look.\n\nWe'll start with the lower-level APIs and move our way up to the higher-level ones. We chose this route because the higher-level APIs are built on top of the lower-level APIs. However, when choosing an API for your use case, you should consider them in the exact opposite order: choose the highest level abstraction that gets the job done and keep your concurrency model very simple.\n\nIf you're wondering why we are so persistent recommending high-level abstractions and very simple concurrency code, you should read the second part of this article, [challenges of concurrent programming](#challenges-of-concurrent-programming), as well as [Peter Steinberger's thread safety article][400].\n\n\n### Threads\n\n[Threads](http://en.wikipedia.org/wiki/Thread_%28computing%29) are subunits of processes, which can be scheduled independently by the operating system scheduler. Virtually all concurrency APIs are built on top of threads under the hood -- that's true for both Grand Central Dispatch and operation queues.\n\nMultiple threads can be executed at the same time on a single CPU core (or at least perceived as at the same time). The operating system assigns small slices of computing time to each thread, so that it seems to the user as if multiple tasks are executed at the same time. If multiple CPU cores are available, then multiple threads can be executed truly in parallel, therefore lessening the total time needed for a certain workload.\n\nYou can use the [CPU strategy view](http://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/InstrumentsUserGuide/AnalysingCPUUsageinYourOSXApp/AnalysingCPUUsageinYourOSXApp.html) in Instruments to get some insight of how your code or the framework code you're using gets scheduled for execution on multiple CPU cores.\n\nThe important thing to keep in mind is that you have no control over where and when your code gets scheduled, and when and for how long its execution will be paused in order for other tasks to take their turn. This kind of thread scheduling is a very powerful technique. However, it also comes with great complexity, which we will investigate later on.\n\nLeaving this complexity aside for a moment, you can either use the [POSIX thread](http://en.wikipedia.org/wiki/POSIX_Threads) API, or the Objective-C wrapper around this API, `NSThread`, to create your own threads. Here's a small sample that finds the minimum and maximum in a set of 1 million numbers using `pthread`. It spawns off 4 threads that run in parallel. It should be obvious from this example why you wouldn't want to use pthreads directly.\n\n```objc\n#import