[doc/io,win] Improve file locking documentation for Windows
This CL improves the documentation for the lockSync and lock methods
in `RandomAccessFile`, specifically addressing file locking behavior
on Windows.
CoreLibraryReviewExempt: `dart:io` is VM only.
Closes: https://github.com/dart-lang/sdk/issues/56378
Change-Id: Ia1569a8e3b066b9b36d6f38cd446cfaa5470321d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/379040
Reviewed-by: Lasse Nielsen <lrn@google.com>
Reviewed-by: Slava Egorov <vegorov@google.com>
Commit-Queue: Daco Harkes <dacoharkes@google.com>
diff --git a/sdk/lib/io/file.dart b/sdk/lib/io/file.dart
index 9b47226..040a04b 100644
--- a/sdk/lib/io/file.dart
+++ b/sdk/lib/io/file.dart
@@ -921,6 +921,13 @@
/// 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".
+ ///
+ /// On Windows, locking a file associates the lock with the specific file
+ /// handle used to acquire the lock. If the same file is opened again with a
+ /// different handle (even within the same process), attempts to write to the
+ /// locked region using the new handle will fail. To ensure successful writes
+ /// after locking, use the same [RandomAccessFile] object that acquired the
+ /// lock for subsequent write operations.
Future<RandomAccessFile> lock(
[FileLock mode = FileLock.exclusive, int start = 0, int end = -1]);
@@ -958,6 +965,12 @@
/// is not the case unlocking will result in the OS error "The segment is
/// already unlocked".
///
+ /// On Windows, locking a file associates the lock with the specific file
+ /// handle used to acquire the lock. If the same file is opened again with a
+ /// different handle (even within the same process), attempts to write to the
+ /// locked region using the new handle will fail. To ensure successful writes
+ /// after locking, use the same [RandomAccessFile] object that acquired the
+ /// lock for subsequent write operations.
void lockSync(
[FileLock mode = FileLock.exclusive, int start = 0, int end = -1]);
