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 {

[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.
  *
  * 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.
+   *
+   * 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();
 
   /**
    * 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();
   }
 }