Add support for file locking

sdk/lib/io/file.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * The modes in which a File can be opened.
  */
 class FileMode {
@@ skipping 14 matching lines @@
 /// The mode for opening a file only for reading.
 const READ = FileMode.READ;
 /// The mode for opening a file for reading and writing. The file is
 /// overwritten if it already exists. The file is created if it does not
 /// already exist.
 const WRITE = FileMode.WRITE;
 /// The mode for opening a file for reading and writing to the
 /// 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.
  *
  * A File instance is an object that holds a [path] on which operations can
  * be performed.
  * You can get the parent directory of the file using the getter [parent],
  * a property inherited from [FileSystemEntity].
  *
  * Create a new File object with a pathname to access the specified file on the
  * file system from your program.
@@ skipping 646 matching lines @@
   Future<RandomAccessFile> flush();
 
   /**
    * Synchronously flushes the contents of the file to disk.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   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();
 
   /**
    * Gets the path of the file underlying this RandomAccessFile.
    */
   String get path;
 }
 
@@ skipping 43 matching lines @@
       sb.write(": $osError");
       if (path != null) {
         sb.write(", path = '$path'");
       }
     } else if (path != null) {
       sb.write(": $path");
     }
     return sb.toString();
   }
 }