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..767308e4288a35446ebb25541b77c57afb8a49f5 100644
--- a/sdk/lib/io/file.dart
+++ b/sdk/lib/io/file.dart
@@ -32,6 +32,18 @@ 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 {

[Lasse Reichstein Nielsen, 2015/01/08 11:59:22]

Make this an enum.

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

Not yet. Enums still not enabled by default in dart2js.

+  final int _lock;
+
+  /// Shared file lock.
+  static const SHARED = const FileLock._internal(0);
+  /// Exclusive file lock.

[kustermann, 2015/01/08 12:54:27]

empty line before '///'.

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

Done.

+  static const EXCLUSIVE = const FileLock._internal(1);
+
+  const FileLock._internal(this._lock);
+}
+
 /**
  * A reference to a file on the file system.
  *
@@ -698,6 +710,93 @@ abstract class RandomAccessFile {
   void flushSync();
 
   /**
+   * Locks the file or part of the file.
+   *
+   * 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.
+   *
+   * By default an exclusive lock will be obtained, but that can be overridden
+   * by the [mode] argument.
+   *
+   * 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.

[Lasse Reichstein Nielsen, 2015/01/08 11:59:22]

Worth mentioning that advisory locks are not actually locking the file?

Also worth mentioning is that this is a per-process lock, so you share locks and
unlocks with everybody else in the same process, including other isolates.

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

Done.

+   *
+   * 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".
+   */
+  Future<RandomAccessFile> lock(
+      [int start, int end, FileLock mode = FileLock.EXCLUSIVE]);

[Lasse Reichstein Nielsen, 2015/01/08 11:59:22]

As discussed, move mode to first argument.
Maybe omit start/end, especially if it doesn't mean the same thing between
Unixes and Windows.

Maybe default start to 0, as other range functions.

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

Done.

+
+  /**
+   * Synchronously locks the file or part of the file.
+   *
+   * 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.
+   *
+   * By default an exclusive lock will be obtained, but that can be overridden
+   * by the [mode] argument.
+   *
+   * 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.
+   *
+   * 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([int start, int end, FileLock mode = FileLock.EXCLUSIVE]);
+
+  /**
+   * 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.
+   */
+  Future<RandomAccessFile> unlock([int start, int end]);

[Lasse Reichstein Nielsen, 2015/01/08 11:59:22]

Maybe default start to 0.

[kustermann, 2015/01/08 12:54:27]

Why is lockSync(), unlockSync() returning void and lock()/unlock() returning not
Future but Future<RandomAccessFile>???

This is not symmetric, and what it returns must be the same instance as the
where the methods are called anyway, righ?

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

This is the convention for RandomAccessFile. All async operations which does not
have a "value" completes with this.

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

Done.

+
+  /**
+   * 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, int end]);
+
+  /**
    * Returns a human-readable string for this RandomAccessFile instance.
    */
   String toString();