Prototype of Files service.

services/file_manager/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.
+
+//FIXME FIXME FIXME: 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
+//  - timestamps are int64, milliseconds since Unix epoch (i.e., dubious)
+
+module mojo.files;
+
+import "services/file_manager/types.mojom";
+
+interface File {
+  Close() => (Error err);
+
+  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);
+
+  ReadStream(handle<data_pipe_producer> source, int64 offset, Whence whence)

[darin (slow to review), 2015/02/06 23:36:11]

nit: maybe this should be called ReadToStream? shouldn't the first parameter be
a data_pipe_consumer here? it is the intended recipient for the data that was
read from the file, right? or, is this really a function that reads from the
data_pipe_consumer and copies (writes) to the file? maybe naming consistency
with the Read/Write methods is valuable.

[vtl, 2015/02/06 23:51:50]

Maybe?
Nope.
Yes, which is why the receiver (e.g., the file manager) needs the producer
handle; the caller is the consumer.

[darin (slow to review), 2015/02/07 00:05:53]

OK, yes... I got myself confused. The name ReadStream sounds like it means "read
the stream" or "read (from) stream" rather than "read data from file copying
output to stream". hence, the ReadToStream suggestion.

+      => (Error error);
+  WriteStream(handle<data_pipe_consumer> sink, int64 offset, Whence whence)
+      => (Error error);
+
+  Tell() => (Error error, int64 position);

[darin (slow to review), 2015/02/06 23:36:11]

is the point of these to enable some read-ahead optimizations for the Read
method? alternatively, the client could just maintain their own concept of a
cursor.

[vtl, 2015/02/06 23:51:49]

If you want to support POSIX-ish/standard C library-ish functionality, you need
a shared cursor.

(Admittedly, you may only want those semantics within a single app. But then
you'd be forced to wrap everything extremely thoroughly and multiplex "fake FDs"
to Files.)

[darin (slow to review), 2015/02/07 00:05:53]

OK, I see. 

+  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).
+  Touch(FileTimes? times) => (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 access_flags, 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);

[darin (slow to review), 2015/02/06 23:36:11]

how about Read/Write variants that take a SHM handle as a parameter? that way
the caller can efficiently ask to have data copied from the file into SHM
without having to map the entire file.

[vtl, 2015/02/06 23:51:49]

They don't have to map the entire file (buffer handles support arbitrary
mapping).

Moreover, if you're doing that sort of thing (setting up/tearing down shmem on a
per read/write basis), you'd probably be better off just sending/copying the
data most of the time anyway.

[darin (slow to review), 2015/02/07 00:05:53]

I see.
Oh, I was thinking about cases where someone might want to copy a range from a
file (or multiple files) into a piece of memory. Using SHM could be useful in
that case. Having to map the file and dereference to achieve the effect suffers
from blocking the client while the file is synchronously brought into memory.

+
+  // TODO(vtl): Add a "watch"?
+};