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
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 acquir
|
+ 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 rat
Søren Gjesse
2015/01/14 13:06:06
This was decided based on:
1. Locking the while f
|
+ |
+ /** |
+ * 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(); |