Document and move ReadResult interface to api.go.

fuse/api.go

@@ -144,6 +144,7 @@ type PathNodeFsOptions struct {
 	ClientInodes bool
 }
 
+
 // A File object should be returned from FileSystem.Open and
 // FileSystem.Create.  Include DefaultFile into the struct to inherit
 // a default null implementation.  
@@ -176,6 +177,21 @@ type File interface {
 	Utimens(atimeNs int64, mtimeNs int64) Status
 }
 
+// The result of Read is an array of bytes, but for performance
+// reasons, we can also return data as a file-descriptor/offset/size
+// tuple.  If the backing store for a file is another filesystem, this
+// reduces the amount of copying between the kernel and the FUSE
+// server.  The ReadResult interface captures both cases.
+type ReadResult interface {
+	// Returns the raw bytes for the read, possibly using the
+	// passed buffer. The buffer should be larger than the return
+	// value from Size.
+	Bytes(buf []byte) []byte
+
+	// Size returns how many bytes this return value takes at most.
+	Size() int
+}
+
 // Wrap a File return in this to set FUSE flags.  Also used internally
 // to store open file data.
 type WithFlags struct {

fuse/read.go

@@ -5,19 +5,9 @@ import (
 	"syscall"
 )
 
-type ReadResult interface {
-	Bytes(buf []byte) []byte
-	Size() int
-}
 
-// The result of Read is an array of bytes, but for performance
-// reasons, we can also return data as a file-descriptor/offset/size
-// tuple.  If the backing store for a file is another filesystem, this
-// reduces the amount of copying between the kernel and the FUSE
-// server
-//
-// If at any point,  the raw data is needed, ReadResult.Read() will
-// load the raw data into the Data member.
+
+// ReadResultData is the read return for returning bytes directly.
 type ReadResultData struct {
 	// Raw bytes for the read.
 	Data []byte
@@ -31,9 +21,9 @@ func (r *ReadResultData) Bytes(buf []byte) []byte {
 	return r.Data
 }
 
+// ReadResultFd is the read return for zero-copy file data.
 type ReadResultFd struct {
-	// If Data is nil and Status OK, splice from the following
-	// file.
+	// Splice from the following file.
 	Fd uintptr
 
 	// Offset within Fd, or -1 to use current offset.