Add support for file locking

sdk/lib/io/file.dart

Index: sdk/lib/io/file.dart
diff --git a/sdk/lib/io/file.dart b/sdk/lib/io/file.dart
index 9565d4dc38b41002877e4cc99cf03f7c7153930a..711793a007eba55fce6e56b128912460992809bb 100644
--- a/sdk/lib/io/file.dart
+++ b/sdk/lib/io/file.dart
@@ -32,6 +32,20 @@ const WRITE = FileMode.WRITE;
 /// end of it. The file is created if it does not already exist.
 const APPEND = FileMode.APPEND;
 
+
+/// Type of lock when requesting a lock on a file.
+class FileLock {
+  final int _lock;
+
+  /// Shared file lock.
+  static const SHARED = const FileLock._internal(0);
+
+  /// Exclusive file lock.
+  static const EXCLUSIVE = const FileLock._internal(1);
+
+  const FileLock._internal(this._lock);
+}
+
 /**
  * A reference to a file on the file system.
  *
@@ -698,6 +712,104 @@ abstract class RandomAccessFile {
   void flushSync();
 
   /**
+   * Locks the file or part of the file.
+   *
+   * By default an exclusive lock will be obtained, but that can be overridden
+   * by the [mode] argument.
+   *
+   * Locks the byte range from [start] to [end] of the file, with the
+   * byte at position `end` not included. If no arguments are
+   * specified, the full file is locked, If only `start` is specified
+   * the file is locked from byte position `start` to the end of the
+   * file, no matter how large it grows. It is possible to specify an
+   * explicit value of `end` which is past the current length of the file.
+   *
+   * To obtain an exclusive lock on a file it must be opened for writing.
+   *
+   * *NOTE* file locking does have slight differences in behavior across
+   * platforms:
+   *
+   * On Linux and Mac OS this uses advisory locks, which have the
+   * surprising semantics that all locks associated with a given file
+   * are removed when *any* file descriptor for that file is closed by
+   * the process. Note that this does not actually lock the file for
+   * access. Also note that advisory locks are on a process
+   * level. This means that several isolates in the same process can
+   * obtain an exclusive lock on the same file.

[nweiz, 2015/01/14 01:09:37]

Consider also explaining the semantics of locking across isolates on Windows,
even if they're more intuitive.

[Søren Gjesse, 2015/01/14 13:06:06]

Will do.

+   *
+   * On Windows the regions used for lock and unlock needs to match. If that
+   * is not the case unlocking will result in the OS error "The segment is
+   * already unlocked".
+   */

[nweiz, 2015/01/16 00:06:45]

Mention what happens when the lock can't be acquired. In particular, what
specific error should users check for? Is that error consistent across systems?

+  Future<RandomAccessFile> lock(
+      [FileLock mode = FileLock.EXCLUSIVE, int start = 0, int end]);

[nweiz, 2015/01/14 01:09:37]

It would be really nice to have these be named rather than positional
parameters. If I just want to set [start], I shouldn't have to explicitly set
[mode] as well.

[Søren Gjesse, 2015/01/14 13:06:06]

This was decided based on:

1. Locking the while file is the most common case, so just specifying mode
should be easy.
2. All existing dart:io methods taking start/end use positional parameters.

+
+  /**
+   * Synchronously locks the file or part of the file.
+   *
+   * By default an exclusive lock will be obtained, but that can be overridden
+   * by the [mode] argument.
+   *
+   * Locks the byte range from [start] to [end] of the file ,with the
+   * byte at position `end` not included. If no arguments are
+   * specified, the full file is locked, If only `start` is specified
+   * the file is locked from byte position `start` to the end of the
+   * file, no matter how large it grows. It is possible to specify an
+   * explicit value of `end` which is past the current length of the file.
+   *
+   * To obtain an exclusive lock on a file it must be opened for writing.
+   *
+   * *NOTE* file locking does have slight differences in behavior across
+   * platforms:
+   *
+   * On Linux and Mac OS this uses advisory locks, which have the
+   * surprising semantics that all locks associated with a given file
+   * are removed when *any* file descriptor for that file is closed by
+   * the process. Note that this does not actually lock the file for
+   * access. Also note that advisory locks are on a process
+   * level. This means that several isolates in the same process can
+   * obtain an exclusive lock on the same file.
+   *
+   * On Windows the regions used for lock and unlock needs to match. If that
+   * is not the case unlocking will result in the OS error "The segment is
+   * already unlocked".
+   *
+   */
+  void lockSync([FileLock mode = FileLock.EXCLUSIVE, int start = 0, int end]);
+
+  /**
+   * Unlocks the file or part of the file.
+   *
+   * Unlocks the byte range from [start] to [end] of the file, with
+   * the byte at position `end` not included. If no arguments are
+   * specified, the full file is unlocked, If only `start` is
+   * specified the file is unlocked from byte position `start` to the
+   * end of the file.
+   *
+   * *NOTE* file locking does have slight differences in behavior across
+   * platforms:
+   *
+   * See [lock] for more details.
+   */

[nweiz, 2015/01/16 00:06:45]

What is the Future returned by this waiting for?

+  Future<RandomAccessFile> unlock([int start = 0, int end]);
+
+  /**
+   * Synchronously unlocks the file or part of the file.
+   *
+   * Unlocks the byte range from [start] to [end] of the file, with
+   * the byte at position `end` not included. If no arguments are
+   * specified, the full file is unlocked, If only `start` is
+   * specified the file is unlocked from byte position `start` to the
+   * end of the file.
+   *
+   * *NOTE* file locking does have slight differences in behavior across
+   * platforms:
+   *
+   * See [lockSync] for more details.
+   */
+  void unlockSync([int start = 0, int end]);
+
+  /**
    * Returns a human-readable string for this RandomAccessFile instance.
    */
   String toString();