Prototype of Files service.

services/files/file.mojom

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// TODO(vtl): notes to self:
+//  - file offsets, file positions, and file sizes are int64 (though positions
+//    and sizes must always be non-negative)
+//  - buffer size parameters (for read/write) are uint32
+
+module mojo.files;
+
+import "services/files/types.mojom";
+
+// TODO(vtl): Write comments.
+interface File {
+  Close() => (Error err);

[qsr, 2015/03/02 12:46:40]

What can you do with a connected closed file? If nothing, should we get rid of
this and just use closing the handle as the right signal?

[viettrungluu, 2015/03/02 18:10:59]

Not very much.
There are two reasons to have an explicit close:

* It acts as an explicit flush with acknowledgement.
* It gives a chance for more errors to be reported. (close(2) says: "Not
checking the return value of close() is a common  but  nevertheless serious 
programming error.  It is quite possible that errors on a previous write(2)
operation are first reported at the final close()." Of course, it then goes to
undermine itself somewhat in the following paragraph.)

[qsr, 2015/03/03 11:56:44]

 Ok
 Hum. Should we have a flush method? I don't see any documentation on the
different write method relative to flushing.

[viettrungluu, 2015/03/03 18:50:35]

I meant that it's similar in effect to closing the message pipe, except with
acknowledgement. (Possibly we should have something analogous to fsync(2) also.
I added a TODO for this.)

In general, I'm a bit nervous about tying a potentially-important operation like
closing to the closure of the message pipe (it may be important since the
implementation may take it as a signal to, e.g., upload/synchronize data).

This is especially true for GCed languages, where releasing the last ref to an
object isn't sufficient to guarantee destruction and thus message pipe closure.
But maybe this means that MojoHandle wrapper objects for GCed languages need
explicit close methods. If that's the case, then we could remove this. WDYT?

+
+  Read(uint32 num_bytes_to_read, int64 offset, Whence whence)
+      => (Error error, array<uint8>? bytes_read);
+  Write(array<uint8> bytes_to_write, int64 offset, Whence whence)
+      => (Error error, uint32 num_bytes_written);
+
+  // TODO(vtl): We definitely want 64 bits for |num_bytes_to_read|; but do we
+  // want it to be signed (this is consistent with |size| values, but
+  // inconsistent with 32-bit |num_bytes_to_read| values)? Do we want to have
+  // separate "read to end" versus "tail" (i.e., keep on reading as more data is
+  // appended) modes, and how would those be signalled?

[qsr, 2015/03/02 12:46:40]

Do you also need a special value of no limit?

[viettrungluu, 2015/03/02 18:10:59]

See TODO above -- we need TWO special values!

+  ReadToStream(handle<data_pipe_producer> source,
+               int64 offset,
+               Whence whence,
+               int64 num_bytes_to_read) => (Error error);
+  WriteFromStream(handle<data_pipe_consumer> sink, int64 offset, Whence whence)
+      => (Error error);
+
+  Tell() => (Error error, int64 position);
+  Seek(int64 offset, Whence whence) => (Error error, int64 position);
+
+  Stat() => (Error error, FileInformation? file_information);
+  Truncate(int64 size) => (Error error);
+  // TODO(vtl): null |times| means "now" (for both atime and mtime).

[qsr, 2015/03/02 12:46:40]

Isn't the comment outdated? You have way to specify now in your data structure,
so you can use null |times| to mean do not modify.

[viettrungluu, 2015/03/02 18:10:59]

Done.

+  Touch(TimespecOrNow? atime, TimespecOrNow? mtime) => (Error error);
+
+  // TODO(vtl): |Dup()| shares the same file description (i.e., mode and
+  // position).
+  Dup(File& file) => (Error error);
+  // TODO(vtl): What are the rules for reopening (w.r.t. changing mode/flags).
+  // E.g., obviously can go from "read-write" to "read", but reverse? (probably
+  // not), can remove "append"? (probably not?). Do we allow "truncate"?
+  Reopen(File& file, uint32 open_flags) => (Error error);
+
+  // TODO(vtl): probably should have access flags (but also exec?); how do these
+  // relate to access mode?
+  AsBuffer() => (Error error, handle<shared_buffer>? buffer);
+
+  // TODO(vtl): Add a "watch"?
+};