Adds blocking file locks.

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 34 matching lines @@
 /// Mode for opening a file for writing *only* to the
 /// end of it. The file is created if it does not already exist.
 const WRITE_ONLY_APPEND = FileMode.WRITE_ONLY_APPEND;
 
 
 /// Type of lock when requesting a lock on a file.
 enum FileLock {
   /// Shared file lock.
   SHARED,
   /// Exclusive file lock.
-  EXCLUSIVE
+  EXCLUSIVE,
+  /// Blocking shared file lock.
+  BLOCKING_SHARED,
+  /// Blocking exclusive file lock.
+  BLOCKING_EXCLUSIVE,
 }
 
 /**
  * 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].
  *
@@ skipping 662 matching lines @@
    *
    * 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.
    *
+   * If [mode] is [FileLock.EXCLUSIVE] or [FileLock.SHARED], an error is
+   * signaled if the lock cannot be obtained. If [mode] is
+   * [FileLock.BLOCKING_EXCLUSIVE] or [FileLock.BLOCKING_SHARED], the
+   * returned [Future] is resolved only when the lock has been obtained.
+   *

[siva, 2016/06/13 15:56:08]

This operation is not synchronous, should we allow the BLOCKING options to be
used in this function as a call to this function can potentially block and seems
to go against the grain of being asynchronous.

[zra, 2016/06/13 16:03:33]

This call is implemented as a request sent to the IO Service thread, which then
makes the potentially blocking call. The calling thread doesn't block. The
returned Future is completed when the response is received from the IO Service
thread.

[Søren Gjesse, 2016/06/13 16:05:09]

The blocking I/O call is dispatched on the "native isolate" thread-pool, so it
will not block other Dart code from running. However performing blocking lock
calls on more files than there are threads in the native isolate can end up
blocking the native isolate is neither of these calls can gain the lock, so care
should be taken in that case.

I cannot remember how many threads are allocated for the native isolate.

    * *NOTE* file locking does have slight differences in behavior across
    * platforms:
    *
    * On Linux and OS X 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.
@@ skipping 13 matching lines @@
    *
    * 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.
    *
+   * If [mode] is [FileLock.EXCLUSIVE] or [FileLock.SHARED], an exception is
+   * thrown if the lock cannot be obtained. If [mode] is
+   * [FileLock.BLOCKING_EXCLUSIVE] or [FileLock.BLOCKING_SHARED], the
+   * call returns only after the lock has been obtained.
+   *
    * *NOTE* file locking does have slight differences in behavior across
    * platforms:
    *
    * On Linux and OS X 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.
@@ skipping 95 matching lines @@
       sb.write(": $osError");
       if (path != null) {
         sb.write(", path = '$path'");
       }
     } else if (path != null) {
       sb.write(": $path");
     }
     return sb.toString();
   }
 }