Rename Flow.read to Flow.single_read

README.md

@@ -1237,7 +1237,7 @@ See Eio's own tests for examples, e.g., [tests/switch.md](tests/switch.md).
 
 ## Provider Interfaces
 
-Eio applications use resources by calling functions (such as `Eio.Flow.read`).
+Eio applications use resources by calling functions (such as `Eio.Flow.write`).
 These functions are actually wrappers that call methods on the resources.
 This allows you to define your own resources.
 
@@ -1274,10 +1274,10 @@ it is recommended that you use the functions instead.
 The functions provide type information to the compiler, leading to clearer error messages,
 and may provide extra features or sanity checks.
 
-For example `Eio.Flow.read` is defined as:
+For example `Eio.Flow.single_read` is defined as:
 
 ```ocaml
-let read (t : #Eio.Flow.source) buf =
+let single_read (t : #Eio.Flow.source) buf =
   let got = t#read_into buf in
   assert (got > 0 && got <= Cstruct.length buf);
   got

lib_eio/buf_read.ml

@@ -117,7 +117,7 @@ let ensure_slow_path t n =
       while t.len < n do
         let free_space = Cstruct.of_bigarray t.buf ~off:(t.pos + t.len) in
         assert (t.len + Cstruct.length free_space >= n);
-        let got = Flow.read flow free_space in
+        let got = Flow.single_read flow free_space in
         t.len <- t.len + got
       done;
       assert (buffered_bytes t >= n)

lib_eio/file.ml

@@ -17,7 +17,7 @@ end
     even if more bytes are available. Use {!pread_exact} instead if you require
     the buffer to be filled.
 
-    To read at the current offset, use {!Flow.read} instead. *)
+    To read at the current offset, use {!Flow.single_read} instead. *)
 let pread (t : #ro) ~file_offset bufs =
   let got = t#pread ~file_offset bufs in
   assert (got > 0 && got <= Cstruct.lenv bufs);

lib_eio/flow.ml

@@ -15,7 +15,7 @@ class virtual source = object (_ : <Generic.t; ..>)
   method virtual read_into : Cstruct.t -> int
 end
 
-let read (t : #source) buf =
+let single_read (t : #source) buf =
   let got = t#read_into buf in
   assert (got > 0 && got <= Cstruct.length buf);
   got
@@ -24,7 +24,7 @@ let read_methods (t : #source) = t#read_methods
 
 let rec read_exact t buf =
   if Cstruct.length buf > 0 then (
-    let got = read t buf in
+    let got = single_read t buf in
     read_exact t (Cstruct.shift buf got)
   )
 
@@ -107,3 +107,5 @@ class virtual two_way = object (_ : <source; sink; ..>)
 end
 
 let shutdown (t : #two_way) = t#shutdown
+
+let read = single_read

lib_eio/flow.mli

@@ -16,11 +16,14 @@ class virtual source : object
 end
 
 val read : #source -> Cstruct.t -> int
-(** [read src buf] reads one or more bytes into [buf].
+[@@deprecated "Use single_read if you really want this."]
+
+val single_read : #source -> Cstruct.t -> int
+(** [single_read src buf] reads one or more bytes into [buf].
 
     It returns the number of bytes read (which may be less than the
     buffer size even if there is more data to be read).
-    [read src] just makes a single call to [src#read_into]
+    [single_read src] just makes a single call to [src#read_into]
     (and asserts that the result is in range).
 
     - Use {!read_exact} instead if you want to fill [buf] completely.

lib_eio/mock/flow.ml

@@ -56,7 +56,7 @@ let make ?(pp=pp_default) label =
       while true do
         let size = Handler.run on_copy_bytes in
         let buf = Cstruct.create size in
-        let n = Eio.Flow.read src buf in
+        let n = Eio.Flow.single_read src buf in
         traceln "%s: wrote @[<v>%a@]" label pp (Cstruct.to_string (Cstruct.sub buf 0 n))
       done
     with End_of_file -> ()

lib_eio_linux/eio_linux.ml

@@ -981,7 +981,7 @@ let fallback_copy src dst =
     let buf = Cstruct.create 4096 in
     try
       while true do
-        let got = Eio.Flow.read src buf in
+        let got = Eio.Flow.single_read src buf in
         Low_level.writev dst [Cstruct.sub buf 0 got]
       done
     with End_of_file -> ()
@@ -990,7 +990,7 @@ let fallback_copy src dst =
   let chunk_cs = Uring.Region.to_cstruct chunk in
   try
     while true do
-      let got = Eio.Flow.read src chunk_cs in
+      let got = Eio.Flow.single_read src chunk_cs in
       Low_level.write dst chunk got
     done
   with End_of_file -> ()

lib_eio_luv/eio_luv.ml

@@ -631,7 +631,7 @@ let flow fd = object (_ : <source; sink; ..>)
     let buf = Luv.Buffer.create 4096 in
     try
       while true do
-        let got = Eio.Flow.read src (Cstruct.of_bigarray buf) in
+        let got = Eio.Flow.single_read src (Cstruct.of_bigarray buf) in
         let sub = Luv.Buffer.sub buf ~offset:0 ~length:got in
         File.write fd [sub] |> or_raise
       done
@@ -662,7 +662,7 @@ let socket sock = object
     let buf = Luv.Buffer.create 4096 in
     try
       while true do
-        let got = Eio.Flow.read src (Cstruct.of_bigarray buf) in
+        let got = Eio.Flow.single_read src (Cstruct.of_bigarray buf) in
         let buf' = Luv.Buffer.sub buf ~offset:0 ~length:got in
         Stream.write sock [buf']
       done

tests/buf_reader.md

@@ -40,7 +40,7 @@ end
 
 let read flow n =
   let buf = Cstruct.create n in
-  let len = Eio.Flow.read flow buf in
+  let len = Eio.Flow.single_read flow buf in
   traceln "Read %S" (Cstruct.to_string buf ~len)
 
 let is_digit = function

tests/network.md

@@ -448,7 +448,7 @@ ECONNRESET:
   Eio.Flow.copy_string "foo" a;
   Eio.Flow.close b;     (* Close without reading *)
   try
-    ignore (Eio.Flow.read a (Cstruct.create 1) : int);
+    Eio.Flow.read_exact a (Cstruct.create 1);
     assert false
   with Eio.Net.Connection_reset _ | End_of_file -> traceln "Connection failed (good)";;
 +Connection failed (good)
@@ -492,8 +492,8 @@ Connection refused:
   let a, b = Eio_unix.socketpair ~sw () in
   Fiber.both
     (fun () ->
-       match Eio.Flow.read a (Cstruct.create 1) with
-       | (_ : int) -> failwith "Should have ended!"
+       match Eio.Flow.read_exact a (Cstruct.create 1) with
+       | () -> failwith "Should have ended!"
        | exception End_of_file -> ()
     )
     (fun () -> Eio.Flow.shutdown a `Receive);;
@@ -698,6 +698,8 @@ Exception: Eio__Net.Connection_failure Eio__Time.Timeout.
 
 ## read/write on SOCK_DGRAM
 
+TODO: This is wrong; see https://github.com/ocaml-multicore/eio/issues/342
+
 ```ocaml
 # Eio_main.run @@ fun _ ->
   Switch.run @@ fun sw ->
@@ -708,7 +710,7 @@ Exception: Eio__Net.Connection_failure Eio__Time.Timeout.
   let buf = Cstruct.create 32 in
   let write bufs = Eio.Flow.write a (List.map Cstruct.of_string bufs) in
   let read () =
-    let n = Eio.Flow.read b buf in
+    let n = Eio.Flow.single_read b buf in
     traceln "Got: %d bytes: %S" n Cstruct.(to_string (sub buf 0 n))
   in
   List.iter (fun sbuf -> write [sbuf]) l;