An Introduction to the dart:io Library

Written by Mads Ager
March 2012 (updated October 2012 and February 2013)

The dart:io library is aimed at server-side code that runs on the standalone Dart VM. In this article we will give you a feel for what is currently possible with dart:io by going through a couple of examples.

Dart is a single-threaded programming language. If an operation blocks the Dart thread, the application will make no progress before that operation completes. For scalability it is therefore crucial that no I/O operations block. Instead of blocking on I/O operations, dart:io uses an asynchronous programming model inspired by node.js, EventMachine, and Twisted.

Contents

  1. The Dart VM and the event loop
  2. File system access
  3. Interacting with processes
  4. Writing web servers
  5. Feature requests welcome

The Dart VM and the event loop

Before we dive into asynchronous I/O operations, it might be useful to explain how the standalone Dart VM operates.

When executing a server-side application, the Dart VM runs in an event loop with an associated event queue of pending asynchronous operations. The VM terminates when it has executed the current code to completion and no more pending operations are in the queue.

One simple way to add an event to the event queue is to schedule a function to be called in the future. You can do this by creating a Timer object. The following example registers a timer with the event queue and then drops off the end of main(). Because a pending operation is in the event queue, the VM does not terminate at that point. After one second, the timer fires and the code in the argument callback executes. Once that code executes to completion, no more pending operations are in the event queue and the VM terminates.

import 'dart:async';

main() {
  new Timer(new Duration(seconds:1), () => print('timer'));
  print('end of main');
}

Running this example at the command line, we get:

$ dart timer.dart 
end of main
timer

Had we made the timer repeating by using the Timer.periodic() constructor, the VM would not terminate and would continue to print out ‘timer’ every second.

File system access

The dart:io library provides access to files and directories through the File and Directory classes.

The following example prints its own source code. To determine the location of the source code being executed, we use the Options class.

import 'dart:io';
import 'dart:async';

main() {
  var options = new Options();
  var file = new File(options.script);
  Future<String> finishedReading = file.readAsString(encoding: Encoding.ASCII);
  finishedReading.then((text) => print(text));
}

Notice that the readAsString() method is asynchronous; it returns a Future that will return the contents of the file once the file has been read from the underlying system. This asynchronicity allows the Dart thread to perform other work while waiting for the I/O operation to complete.

To illustrate more detailed file operations, let’s change the example to read the contents only up to the first semicolon and then to print that. You could do this in two ways: either open the file for random access, or open an InputStream for the file and stream in the data.

Here is a version that opens the file for random access operations. The code opens the file for reading and then reads one byte at a time until it encounters the char code for ‘;’.

import 'dart:io';

main() {
  var options = new Options();
  var semicolon = ';'.codeUnitAt(0);
  var result = [];

  new File(options.script).open(mode: FileMode.READ).then((RandomAccessFile file) {
    // Callback to deal with each byte.
    void onByte(int byte) {
      result.add(byte);
      if (byte == semicolon) {
        print(new String.fromCharCodes(result));
        file.close();
      } else {
        file.readByte().then(onByte);
      }
    }
    file.readByte().then(onByte);
  });
}

When you see a use of then(), you are seeing a Future in action. Both the open() and readByte() methods return a Future object.

This code is, of course, a very simple use of random-access operations. Operations are available for writing, seeking to a given position, truncating, and so on.

Let’s implement a version using a stream. The following code opens the file for reading presenting the content as a stream of lists of bytes. Like all streams in Dart you listen on this stream and the data is given in chunks. You can always stop reading more from the file by cancelling the subscription.

import 'dart:io';
import 'dart:async';

main() {
  Options options = new Options();
  List result = [];

  Stream<List<int>> stream = new File(options.script).openRead();
  int semicolon = ';'.codeUnitAt(0);
  StreamSubscription subscription;
  subscription = stream.listen((data) {
    for (int i = 0; i < data.length; i++) {
      result.add(data[i]);
      if (data[i] == semicolon) {
        print(new String.fromCharCodes(result));
        subscription.cancel();
        return;
      }
    }
  });
}

[Stream<List>] is used in multiple places in dart:io: when working with stdin, files, sockets, HTTP connections, and so on. Similarly, [IOSink](http://api.dartlang.org/docs/release/dart_io/IOSink.html)s are used to stream data to stdout, files, sockets, HTTP connections, and so on.

Interacting with processes

For the simple case, use Process.run() to run a process and collect its output. Use run() when you don’t need interactive control over the process.

import 'dart:io';

main() {
  // List all files in the current directory,
  // in UNIX-like operating systems.
  Process.run('ls', ['-l']).then((ProcessResult results) {
    print(results.stdout);
  });
}

You can also start a process by creating a Process object using the Process.start() constructor. Once you have a Process object you can interact with the process by writing data to its stdin sink, reading data from its stderr and stdout streams, and killing the process. When the process exits the exitCode future completes with the exit code of the process.

The following example runs ‘ls -l’ in a separate process and prints the output and the exit code for the process to stdout. Since we are interested in getting lines, we use a StringDecoder, which decodes chunks of bytes into strings followed by a LineTransformer, which splits the strings at line boundaries.

import 'dart:io';

main() {
  Process.start('ls', ['-l']).then((process) {
    process.stdout.transform(new StringDecoder())
                  .transform(new LineTransformer())
                  .listen((String line) => print(line));
    process.stderr.listen((data) { });
    process.exitCode.then((exitCode) {
      print('exit code: $exitCode');
    });
  });
}

Notice that exitCode can complete before all of the lines of output have been processed. Also note that we do not explicitly close the process. In order to not leak resources we have to drain both the stderr and the stdout streams. To do that we set a listener to drain the stderr stream.

Instead of printing the output to stdout, we can use the streaming classes to pipe the output of the process to a file.

import 'dart:io';

main() {
  var output = new File('output.txt').openWrite();
  Process.start('ls', ['-l']).then((process) {
    process.stdout.pipe(output);
    process.stderr.listen((data) { });
    process.exitCode.then((exitCode) {
        print('exit code: $exitCode');
    });
  });
}

Writing web servers

dart:io makes it easy to write HTTP servers and clients. To write a simple web server, all you have to do is create an HttpServer and hook up a listener to its stream of HttpRequests.

Here is a simple web server that just answers ‘Hello, world’ to any request.

import 'dart:io';

main() {
  HttpServer.bind('127.0.0.1', 8080).then((server) {
    server.listen((HttpRequest request) {
      request.response.write('Hello, world');
      request.response.close();
    });
  });
}

Running this application and pointing your browser to ‘http://127.0.0.1:8080’ gives you ‘Hello, world’ as expected.

Let’s add a bit more and actually serve files. The base path for every file that we serve will be the location of the script. If no path is specified in a request we will serve index.html. For a request with a path, we will attempt to find the file and serve it. If the file is not found we will respond with a ‘404 Not Found’ status. We make use of the streaming interface to pipe all the data read from a file directly to the response stream.

import 'dart:io';

_sendNotFound(HttpResponse response) {
  response.statusCode = HttpStatus.NOT_FOUND;
  response.close();
}

startServer(String basePath) {
  HttpServer.bind('127.0.0.1', 8080).then((server) {
    server.listen((HttpRequest request) {
      final String path =
          request.uri.path == '/' ? '/index.html' : request.uri.path;
      final File file = new File('${basePath}${path}');
      file.exists().then((bool found) {
        if (found) {
          // PENDING: Do more security checks here?
          file.fullPath().then((String fullPath) {
            file.openRead()
                .pipe(request.response)
                .catchError((e) { });
          });
        } else {
          _sendNotFound(request.response);
        }
      });
    });
  });
}

main() {
  // Compute base path for the request based on the location of the
  // script and then start the server.
  File script = new File(new Options().script);
  startServer(script.directory.path);
}

Writing HTTP clients is very similar to using the HttpClient class.

Feature requests welcome

The dart:io library is already capable of performing a lot of tasks. As an example of our own use of dart:io, we have rewritten the Dart testing scripts from Python to Dart. All of the tests that you see being run on the buildbot are running on the Dart VM using the dart:io library!

Please give dart:io a spin and let us know what you think. Feature requests are very welcome! When you file a bug or feature request, use the Area-IO label in the issue tracker at dartbug.com.