OLD | NEW |
---|---|
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.io; | 5 part of dart.io; |
6 | 6 |
7 /** | 7 /** |
8 * The modes in which a File can be opened. | 8 * The modes in which a File can be opened. |
9 */ | 9 */ |
10 class FileMode { | 10 class FileMode { |
(...skipping 14 matching lines...) Expand all Loading... | |
25 /// The mode for opening a file only for reading. | 25 /// The mode for opening a file only for reading. |
26 const READ = FileMode.READ; | 26 const READ = FileMode.READ; |
27 /// The mode for opening a file for reading and writing. The file is | 27 /// The mode for opening a file for reading and writing. The file is |
28 /// overwritten if it already exists. The file is created if it does not | 28 /// overwritten if it already exists. The file is created if it does not |
29 /// already exist. | 29 /// already exist. |
30 const WRITE = FileMode.WRITE; | 30 const WRITE = FileMode.WRITE; |
31 /// The mode for opening a file for reading and writing to the | 31 /// The mode for opening a file for reading and writing to the |
32 /// end of it. The file is created if it does not already exist. | 32 /// end of it. The file is created if it does not already exist. |
33 const APPEND = FileMode.APPEND; | 33 const APPEND = FileMode.APPEND; |
34 | 34 |
35 | |
36 /// Type of lock when requesting a lock on a file. | |
37 class FileLock { | |
38 final int _lock; | |
39 | |
40 /// Shared file lock. | |
41 static const SHARED = const FileLock._internal(0); | |
42 | |
43 /// Exclusive file lock. | |
44 static const EXCLUSIVE = const FileLock._internal(1); | |
45 | |
46 const FileLock._internal(this._lock); | |
47 } | |
48 | |
35 /** | 49 /** |
36 * A reference to a file on the file system. | 50 * A reference to a file on the file system. |
37 * | 51 * |
38 * A File instance is an object that holds a [path] on which operations can | 52 * A File instance is an object that holds a [path] on which operations can |
39 * be performed. | 53 * be performed. |
40 * You can get the parent directory of the file using the getter [parent], | 54 * You can get the parent directory of the file using the getter [parent], |
41 * a property inherited from [FileSystemEntity]. | 55 * a property inherited from [FileSystemEntity]. |
42 * | 56 * |
43 * Create a new File object with a pathname to access the specified file on the | 57 * Create a new File object with a pathname to access the specified file on the |
44 * file system from your program. | 58 * file system from your program. |
(...skipping 646 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
691 Future<RandomAccessFile> flush(); | 705 Future<RandomAccessFile> flush(); |
692 | 706 |
693 /** | 707 /** |
694 * Synchronously flushes the contents of the file to disk. | 708 * Synchronously flushes the contents of the file to disk. |
695 * | 709 * |
696 * Throws a [FileSystemException] if the operation fails. | 710 * Throws a [FileSystemException] if the operation fails. |
697 */ | 711 */ |
698 void flushSync(); | 712 void flushSync(); |
699 | 713 |
700 /** | 714 /** |
715 * Locks the file or part of the file. | |
716 * | |
717 * By default an exclusive lock will be obtained, but that can be overridden | |
718 * by the [mode] argument. | |
719 * | |
720 * Locks the byte range from [start] to [end] of the file, with the | |
721 * byte at position `end` not included. If no arguments are | |
722 * specified, the full file is locked, If only `start` is specified | |
723 * the file is locked from byte position `start` to the end of the | |
724 * file, no matter how large it grows. It is possible to specify an | |
725 * explicit value of `end` which is past the current length of the file. | |
726 * | |
727 * To obtain an exclusive lock on a file it must be opened for writing. | |
728 * | |
729 * *NOTE* file locking does have slight differences in behavior across | |
730 * platforms: | |
731 * | |
732 * On Linux and Mac OS this uses advisory locks, which have the | |
733 * surprising semantics that all locks associated with a given file | |
734 * are removed when *any* file descriptor for that file is closed by | |
735 * the process. Note that this does not actually lock the file for | |
736 * access. Also note that advisory locks are on a process | |
737 * level. This means that several isolates in the same process can | |
738 * 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.
| |
739 * | |
740 * On Windows the regions used for lock and unlock needs to match. If that | |
741 * is not the case unlocking will result in the OS error "The segment is | |
742 * already unlocked". | |
743 */ | |
nweiz
2015/01/16 00:06:45
Mention what happens when the lock can't be acquir
| |
744 Future<RandomAccessFile> lock( | |
745 [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
| |
746 | |
747 /** | |
748 * Synchronously locks the file or part of the file. | |
749 * | |
750 * By default an exclusive lock will be obtained, but that can be overridden | |
751 * by the [mode] argument. | |
752 * | |
753 * Locks the byte range from [start] to [end] of the file ,with the | |
754 * byte at position `end` not included. If no arguments are | |
755 * specified, the full file is locked, If only `start` is specified | |
756 * the file is locked from byte position `start` to the end of the | |
757 * file, no matter how large it grows. It is possible to specify an | |
758 * explicit value of `end` which is past the current length of the file. | |
759 * | |
760 * To obtain an exclusive lock on a file it must be opened for writing. | |
761 * | |
762 * *NOTE* file locking does have slight differences in behavior across | |
763 * platforms: | |
764 * | |
765 * On Linux and Mac OS this uses advisory locks, which have the | |
766 * surprising semantics that all locks associated with a given file | |
767 * are removed when *any* file descriptor for that file is closed by | |
768 * the process. Note that this does not actually lock the file for | |
769 * access. Also note that advisory locks are on a process | |
770 * level. This means that several isolates in the same process can | |
771 * obtain an exclusive lock on the same file. | |
772 * | |
773 * On Windows the regions used for lock and unlock needs to match. If that | |
774 * is not the case unlocking will result in the OS error "The segment is | |
775 * already unlocked". | |
776 * | |
777 */ | |
778 void lockSync([FileLock mode = FileLock.EXCLUSIVE, int start = 0, int end]); | |
779 | |
780 /** | |
781 * Unlocks the file or part of the file. | |
782 * | |
783 * Unlocks the byte range from [start] to [end] of the file, with | |
784 * the byte at position `end` not included. If no arguments are | |
785 * specified, the full file is unlocked, If only `start` is | |
786 * specified the file is unlocked from byte position `start` to the | |
787 * end of the file. | |
788 * | |
789 * *NOTE* file locking does have slight differences in behavior across | |
790 * platforms: | |
791 * | |
792 * See [lock] for more details. | |
793 */ | |
nweiz
2015/01/16 00:06:45
What is the Future returned by this waiting for?
| |
794 Future<RandomAccessFile> unlock([int start = 0, int end]); | |
795 | |
796 /** | |
797 * Synchronously unlocks the file or part of the file. | |
798 * | |
799 * Unlocks the byte range from [start] to [end] of the file, with | |
800 * the byte at position `end` not included. If no arguments are | |
801 * specified, the full file is unlocked, If only `start` is | |
802 * specified the file is unlocked from byte position `start` to the | |
803 * end of the file. | |
804 * | |
805 * *NOTE* file locking does have slight differences in behavior across | |
806 * platforms: | |
807 * | |
808 * See [lockSync] for more details. | |
809 */ | |
810 void unlockSync([int start = 0, int end]); | |
811 | |
812 /** | |
701 * Returns a human-readable string for this RandomAccessFile instance. | 813 * Returns a human-readable string for this RandomAccessFile instance. |
702 */ | 814 */ |
703 String toString(); | 815 String toString(); |
704 | 816 |
705 /** | 817 /** |
706 * Gets the path of the file underlying this RandomAccessFile. | 818 * Gets the path of the file underlying this RandomAccessFile. |
707 */ | 819 */ |
708 String get path; | 820 String get path; |
709 } | 821 } |
710 | 822 |
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
754 sb.write(": $osError"); | 866 sb.write(": $osError"); |
755 if (path != null) { | 867 if (path != null) { |
756 sb.write(", path = '$path'"); | 868 sb.write(", path = '$path'"); |
757 } | 869 } |
758 } else if (path != null) { | 870 } else if (path != null) { |
759 sb.write(": $path"); | 871 sb.write(": $path"); |
760 } | 872 } |
761 return sb.toString(); | 873 return sb.toString(); |
762 } | 874 } |
763 } | 875 } |
OLD | NEW |