Processing an Entire File Linearly Using Streams

If you always read or write a file’s contents from start to finish, streams provide a simple interface for doing so asynchronously. Streams are typically used for managing sockets and other types of sources where data may become available over time. However, you can also use streams to read or write an entire file in one or more bursts. There are two types of streams available:

• Use an NSOutputStream to write data sequentially to disk.

• Use an NSInputStream object to read data sequentially from disk.

Stream objects use the run loop of the current thread to schedule read and write operations on the stream. An input stream wakes up the run loop and notifies its delegate when there is data waiting to be read. An output stream wakes up the run loop and notifies its delegate when there is space available for writing data. When operating on files, this behavior usually means that the run loop is woken up several times in quick succession so that your delegate code can read or write the file data. It also means that your delegate code is called repeatedly until you close the stream object, or in the case of input streams until the stream reaches the end of the file.

For information and examples about how to set up and use stream objects to read and write data, see Stream Programming Guide.

Processing a File Using GCD

Grand Central Dispatch provides several different ways to read or write the content of files asynchronously:

• Create a dispatch I/O channel and use it to read or write data.

• Use the dispatch_read or dispatch_write convenience functions to perform a single asynchronous operation.

• Create a dispatch source to schedule the execution of a custom event handler block, in which you use standard POSIX calls to read or write data from the file.

Dispatch I/O channels are the preferred way to read and write files because they give you direct control over when file operations occur but still allow you to process the data asynchronously on a dispatch queue. A dispatch I/O channel is an dispatch_io_t structure that identifies the file whose contents you want to read or write. Channels can be configured for stream-based access or random access of files. A stream-based channel forces you to read or write file data sequentially, whereas a random-access channel lets you read or write at any offset from the beginning of the file.

If you do not want the trouble of creating and managing a dispatch I/O channel, you can use the dispatch_read or dispatch_write functions to perform a single read or write operation on a file descriptor. These methods are convenient for situations where you do not want or need the overhead of creating and managing a dispatch I/O channel. However, you should use them only when performing a single read or write operation on a file. If you need to perform multiple operations on the same file, creating a dispatch I/O channel is much more efficient.

Dispatch sources allow you to process files in a way that is similar to Cocoa stream objects. Like stream objects, they are used more often with sockets or data sources that send and receive data sporadically but they can still be used with files. A dispatch source schedules its associated event handler block whenever there is data waiting to be read or space available for writing. For files, this usually results in the block being scheduled repeatedly and in quick succession until you explicitly cancel the dispatch source or it reaches the end of the file it is reading.

For more information about creating and using dispatch sources, see Concurrency Programming Guide. For information about the dispatch_read or dispatch_write functions, or any other GCD functions, see Grand Central Dispatch (GCD) Reference.

-(void)openChannelWithURL:(NSURL*)anURL {

   NSString* filePath = [anURL path];

   self.channel = dispatch_io_create_with_path(DISPATCH_IO_RANDOM,

                      [filePath UTF8String],   // Convert to C-string

                      O_RDONLY,                // Open for reading

                      0,                       // No extra flags

                      dispatch_get_main_queue(),

                      ^(int error){

                         // Cleanup code for normal channel operation.

                         // Assumes that dispatch_io_close was called elsewhere.

                         if (error == 0) {

                            dispatch_release(self.channel);

                            self.channel = NULL;

                         }

                      });

}

dispatch_io_read(self.channel,

                 1024,                        // 1024 bytes into the file

                 1024,                        // Read the next 1024 bytes

                 dispatch_get_main_queue(),   // Process the bytes on the main thread

                 ^(bool done, dispatch_data_t data, int error){

                     if (error == 0) {

                        // Process the bytes.

                     }

                 });

- (void)readContentsOfFile:(NSURL*)anURL {

   // Open the channel for reading.

   NSString*   filePath = [anURL path];

   self.channel = dispatch_io_create_with_path(DISPATCH_IO_RANDOM,

                       [filePath UTF8String],   // Convert to C-string

                       O_RDONLY,                // Open for reading

                       0,                       // No extra flags

                       dispatch_get_main_queue(),

                       ^(int error){

                          // Cleanup code

                          if (error == 0) {

                             dispatch_release(self.channel);

                             self.channel = nil;

                          }

                      });

   // If the file channel could not be created, just abort.

   if (!self.channel)

      return;

    // Get the file size.

    NSNumber* theSize;

    NSInteger fileSize = 0;

    if ([anURL getResourceValue:&theSize forKey:NSURLFileSizeKey error:nil])

        fileSize = [theSize integerValue];

   // Break the file into 1024 size strings.

   size_t chunkSize = 1024;

   off_t  currentOffset = 0;

   for (currentOffset = 0; currentOffset < fileSize; currentOffset += chunkSize) {

      dispatch_io_read(self.channel, currentOffset, chunkSize, dispatch_get_main_queue(),

                     ^(bool done, dispatch_data_t data, int error){

                        if (error)

                           return;

                        // Build strings from the data.

                        dispatch_data_apply(data, (dispatch_data_applier_t)^(dispatch_data_t region,

                                               size_t offset, const void *buffer, size_t size){

                           NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];

                           NSString* aString = [[[NSString alloc] initWithBytes:buffer

                                         length:size encoding:NSUTF8StringEncoding] autorelease];

                           [self addString:aString toFile:anURL];  // Custom method.

                           [pool release];

                           return true;  // Keep processing if there is more data.

                        });

                     });

    }

}

Building Your Content in Memory and Writing It to Disk All at Once

The simplest way to manage the reading and writing of file data is all at once. This works well for custom document types where you expect the size of the document’s on-disk representation to remain reasonably small. You would not want to do this for multimedia files or for files whose size can grow to many megabytes in size.

For custom document types that use a binary or private file format, you can use the NSData or NSMutableData class to transfer your custom data to and from disk. You can create new data objects in many different ways. For example, you can use a keyed archiver object to convert a graph of objects into a linear stream of bytes enclosed in a data object. If you have a binary file format that is very structured, you can append bytes to an NSMutableData object and build your data object piece by piece. When you are ready to write the data object to disk, use the writeToURL:atomically: or writeToURL:options:error: method. These methods allow you to create the corresponding on-disk file in one step.

To read data back from disk, use the initWithContentsOfURL:options:error: method to obtain a data object based on the contents of your file. You can use this data object to reverse the process you used when creating it. Thus, if you used a keyed archiver to create the data object, you can use a keyed unarchiver to re-create your object graph. If you wrote the data out piece by piece, you can parse the byte stream in the data object and use it to reconstruct your document’s data structures.

Apps that use the NSDocument infrastructure typically interact with the file system indirectly using NSData objects. When the user saves a document, the infrastructure prompts the corresponding NSDocument object for a data object to write to disk. Similarly, when the user opens an existing document, it creates the document object and passes it a data object with which to initialize itself.

For more information about the NSData and NSMutableData classes, see Foundation Framework Reference. For more information about using the document infrastructure in a macOS app, see Mac App Programming Guide.

Reading and Writing Files Using NSFileHandle

The use of the NSFileHandle class closely parallels the process for reading and writing files at the POSIX level. The basic process is that you open the file, issue read or write calls, and close the file when you are done. In the case of NSFileHandle, you open the file automatically when you create an instance of the class. The file handle object acts as a wrapper for the file, managing the underlying file descriptor for you. Depending on whether you requested read access, write access, or both, you then call the methods of NSFileHandle to read or write actual bytes. When you are done, you release your file handle object to close the file.

Listing 7-3 shows a very simple method that reads the entire contents of a file using a file handle object. The fileHandleForReadingFromURL:error: method creates the file handle object as an autoreleased object, which causes it to be released automatically at some point after this method returns.

Listing 7-3  Reading the contents of a file using NSFileHandle

- (NSData*)readDataFromFileAtURL:(NSURL*)anURL {

    NSFileHandle* aHandle = [NSFileHandle fileHandleForReadingFromURL:anURL error:nil];

    NSData* fileContents = nil;

    if (aHandle)

        fileContents = [aHandle readDataToEndOfFile];

    return fileContents;

}

For more information about the methods of the NSFileHandle class, see NSFileHandle Class Reference.

Managing Disk Reads and Writes at the POSIX Level

If you prefer to use C-based functions for your file management code, the POSIX layer offers standard functions for working with files. At the POSIX level, you identify a file using a file descriptor, which is an integer value that identifies an open file uniquely within your app. You pass this file descriptor to any subsequent functions that require it. The following list contains the main POSIX functions you use to manipulate files:

• Use the open function to obtain a file descriptor for your file.

• Use the pread, read, or readv function to read data from an open file descriptor. For information about these functions, see pread.

• Use the pwrite, write, or writev function to write data to an open file descriptor. For information about these functions, see pwrite.

• Use the lseek function to reposition the current file pointer and change the location at which you read or write data.

• Use the pclose function to close the file descriptor when you are done with it.

Listing 7-4 shows a simple function that uses POSIX calls to read the first 1024 bytes of a file and return them in an NSData object. If the file has fewer than 1024 bytes, the method reads as many bytes as possible and truncates the data object to the actual number of bytes.

Listing 7-4  Reading the contents of a file using POSIX functions

- (NSData*)readDataFromFileAtURL:(NSURL*)anURL {

    NSString* filePath = [anURL path];

    fd = open([filePath UTF8String], O_RDONLY);

    if (fd == -1)

        return nil;

    NSMutableData* theData = [[[NSMutableData alloc] initWithLength:1024] autorelease];

    if (theData) {

        void* buffer = [theData mutableBytes];

        NSUInteger bufferSize = [theData length];

        NSUInteger actualBytes = read(fd, buffer, bufferSize);

        if (actualBytes < 1024)

            [theData setLength:actualBytes];

    }

    close(fd);

    return theData;

}

Because there is a limit to the number of open file descriptors an app may have at any given time, you should always close file descriptors as soon as you are done using them. File descriptors are used not only for open files but for communications channels such as sockets and pipes. And your code is not the only entity creating file descriptors for your app. Every time you load a resource file or use a framework that communicates over the network, the system creates a file descriptor on behalf of your code. If your code opens large numbers of sockets or files and never closes them, system frameworks may not be able to create file descriptors at critical times.