Update documentation for RandomAccessFile

Update documentation for RandomAccessFile

R=kustermann@google.com, lrn@google.com
BUG=http://dartbug.com/21516

Committed: https://code.google.com/p/dart/source/detail?r=41548

[kustermann, 2014-11-06 08:55:13]

kustermann@google.com changed reviewers:
+ kustermann@google.com

[kustermann, 2014-11-06 08:55:13]

LGTM

[Lasse Reichstein Nielsen, 2014-11-06 09:18:39]

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart
File sdk/lib/io/file.dart (right):

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:500: * file. [RandomAccessFile] objects are obtained by
calling the
New paragraph after "file.".

Use `RandomAccessFile` instead of [RandomAccessFile] for all but the first
reference (and maybe even for that, we are already at the [RandomAccessFile]
declaration, and you should never have a link to where you already are).

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:503: * A [RandomAccessFile] have both asynchronous and
synchronous
Swap "synchronous" and "asynchronous". (It sounds a little odd to me this way,
I'd prefer the "foo" before the "non-foo" in "both foo and non-foo".)

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:505: * whereas the synchronous methods will block the
current isolate
... will return the result directly, and block the current isolate until the
result is ready.

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:510: * already in progress a [FileSystemException] is
thrown.
Why the restriction? It would be (much!) better to just not have that
restriction, even if it would require keeping multiple file descriptors under
the hood or similar shenanigans.

Is there any way to detect if a RandomAccessFile is currently performing an
async operation? If not, consider adding an "isActive" flag (or similar).

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:513: * synchronous methods. This will also throw a
[FileSystemException].
Definitely need a way to see if it's safe.

[Søren Gjesse, 2014-11-06 12:05:39]

Committed patchset #2 (id:20001) manually as 41548 (presubmit successful).

[Søren Gjesse, 2014-11-06 12:06:10]

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart
File sdk/lib/io/file.dart (right):

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:500: * file. [RandomAccessFile] objects are obtained by
calling the
On 2014/11/06 09:18:39, Lasse Reichstein Nielsen wrote:
> New paragraph after "file.".
> 
> Use `RandomAccessFile` instead of [RandomAccessFile] for all but the first
> reference (and maybe even for that, we are already at the [RandomAccessFile]
> declaration, and you should never have a link to where you already are).

Removed all []'s for RandomAccessFile.

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:503: * A [RandomAccessFile] have both asynchronous and
synchronous
On 2014/11/06 09:18:39, Lasse Reichstein Nielsen wrote:
> Swap "synchronous" and "asynchronous". (It sounds a little odd to me this way,
> I'd prefer the "foo" before the "non-foo" in "both foo and non-foo".)

We are "preferring" async over sync, so I think it makes sense to hve async
first.

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:505: * whereas the synchronous methods will block the
current isolate
On 2014/11/06 09:18:39, Lasse Reichstein Nielsen wrote:
> ... will return the result directly, and block the current isolate until the
> result is ready.

Done.

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:510: * already in progress a [FileSystemException] is
thrown.
On 2014/11/06 09:18:39, Lasse Reichstein Nielsen wrote:
> Why the restriction? It would be (much!) better to just not have that
> restriction, even if it would require keeping multiple file descriptors under
> the hood or similar shenanigans.
> 
> Is there any way to detect if a RandomAccessFile is currently performing an
> async operation? If not, consider adding an "isActive" flag (or similar).

If we are to allow several outstanding async operations we are to define the
precise semantics, which would probably be serializing this, as otherwise you
will get undefined behavior.

There is no isActive, and I am not sure we should add that. The user should keep
track of completing futures before calling the next method.

https://codereview.chromium.org/702363002/diff/20001/sdk/lib/io/file.dart#new...
sdk/lib/io/file.dart:513: * synchronous methods. This will also throw a
[FileSystemException].
On 2014/11/06 09:18:39, Lasse Reichstein Nielsen wrote:
> Definitely need a way to see if it's safe.

Again most likely combining async and sync is a programming error. Open one
RandomAccessFile for sync methods and another one for async, and you are good.
We actually thorough about having a sync and a async RandomAccessFile class to
avoid having both sets of methods on the same class.