Merge pull request #12 from djs55/prepare-commit

[xen] add {read,write} to go along with unsafe_{read,write}. Release 1.1...
mirage · Jul 16, 2014 · 762bfb2 · 762bfb2
2 parents c7ff318 + 306369c
commit 762bfb2
Show file tree

Hide file tree

Showing 8 changed files with 1,875 additions and 651 deletions.
diff --git a/CHANGES b/CHANGES
@@ -1,5 +1,6 @@
-trunk (unreleased)
+1.1.0 (2014-07-16)
 * [xen]: add a prepare/commit interface to control when xenstore/console data is consumed
+* [xen]: add read and write to complement unsafe_read and unsafe_write
 
 1.0.0 (2013-12-07):
 * Standardize indentation by running through ocp-indent.

diff --git a/_oasis b/_oasis
@@ -1,6 +1,6 @@
 OASISFormat: 0.3
 Name:        shared-memory-ring
-Version:     1.0.0
+Version:     1.1.0
 Synopsis:    Xen-style shared memory rings
 Authors:     Anil Madhavapeddy, David Scott
 License:     ISC

diff --git a/_tags b/_tags
@@ -1,7 +1,7 @@
 # OASIS_START
-# DO NOT EDIT (digest: 0187f194f1cc7d35b47699fc297265ac)
-# Ignore VCS directories, you can use the same kind of rule outside 
-# OASIS_START/STOP if you want to exclude directories that contains 
+# DO NOT EDIT (digest: 2f016c8aa42511f75aef9c9d14b144bf)
+# Ignore VCS directories, you can use the same kind of rule outside
+# OASIS_START/STOP if you want to exclude directories that contains
 # useless stuff for the build process
 <**/.svn>: -traverse
 <**/.svn>: not_hygienic
@@ -24,76 +24,76 @@
 "xen/console_ring.cmxs": use_console_ring
 # Library xenstore_ring
 "xen/xenstore_ring.cmxs": use_xenstore_ring
-<xen/*.ml{,i}>: use_shared_memory_ring
 <xen/*.ml{,i}>: pkg_cstruct
 <xen/*.ml{,i}>: pkg_cstruct.syntax
+<xen/*.ml{,i}>: use_shared_memory_ring
 # Library lwt_shared_memory_ring
 "lwt/lwt_shared_memory_ring.cmxs": use_lwt_shared_memory_ring
-<lwt/*.ml{,i}>: use_shared_memory_ring
-<lwt/*.ml{,i}>: pkg_lwt
-<lwt/*.ml{,i}>: pkg_lwt.syntax
 <lwt/*.ml{,i}>: pkg_cstruct
 <lwt/*.ml{,i}>: pkg_cstruct.syntax
+<lwt/*.ml{,i}>: pkg_lwt
+<lwt/*.ml{,i}>: pkg_lwt.syntax
+<lwt/*.ml{,i}>: use_shared_memory_ring
 # Executable ring_test
 <lib_test/ring_test.{native,byte}>: use_libring_test_stubs
-<lib_test/ring_test.{native,byte}>: use_xenstore_ring
-<lib_test/ring_test.{native,byte}>: use_console_ring
-<lib_test/ring_test.{native,byte}>: use_shared_memory_ring
+<lib_test/ring_test.{native,byte}>: pkg_cstruct
+<lib_test/ring_test.{native,byte}>: pkg_cstruct.syntax
 <lib_test/ring_test.{native,byte}>: pkg_lwt
 <lib_test/ring_test.{native,byte}>: pkg_lwt.unix
 <lib_test/ring_test.{native,byte}>: pkg_oUnit
-<lib_test/ring_test.{native,byte}>: pkg_cstruct
-<lib_test/ring_test.{native,byte}>: pkg_cstruct.syntax
-<lib_test/*.ml{,i}>: use_xenstore_ring
-<lib_test/*.ml{,i}>: use_console_ring
-<lib_test/*.ml{,i}>: use_shared_memory_ring
+<lib_test/ring_test.{native,byte}>: use_console_ring
+<lib_test/ring_test.{native,byte}>: use_shared_memory_ring
+<lib_test/ring_test.{native,byte}>: use_xenstore_ring
+<lib_test/*.ml{,i}>: pkg_cstruct
+<lib_test/*.ml{,i}>: pkg_cstruct.syntax
 <lib_test/*.ml{,i}>: pkg_lwt
 <lib_test/*.ml{,i}>: pkg_lwt.unix
 <lib_test/*.ml{,i}>: pkg_oUnit
-<lib_test/*.ml{,i}>: pkg_cstruct
-<lib_test/*.ml{,i}>: pkg_cstruct.syntax
-"lib_test/old_ring_stubs.c": use_xenstore_ring
-"lib_test/old_ring_stubs.c": use_console_ring
-"lib_test/old_ring_stubs.c": use_shared_memory_ring
+<lib_test/*.ml{,i}>: use_console_ring
+<lib_test/*.ml{,i}>: use_shared_memory_ring
+<lib_test/*.ml{,i}>: use_xenstore_ring
+"lib_test/old_ring_stubs.c": pkg_cstruct
+"lib_test/old_ring_stubs.c": pkg_cstruct.syntax
 "lib_test/old_ring_stubs.c": pkg_lwt
 "lib_test/old_ring_stubs.c": pkg_lwt.unix
 "lib_test/old_ring_stubs.c": pkg_oUnit
-"lib_test/old_ring_stubs.c": pkg_cstruct
-"lib_test/old_ring_stubs.c": pkg_cstruct.syntax
+"lib_test/old_ring_stubs.c": use_console_ring
+"lib_test/old_ring_stubs.c": use_shared_memory_ring
+"lib_test/old_ring_stubs.c": use_xenstore_ring
 <lib_test/ring_test.{native,byte}>: custom
 # Executable lwt_test
-<lwt_test/lwt_test.{native,byte}>: use_lwt_shared_memory_ring
-<lwt_test/lwt_test.{native,byte}>: use_shared_memory_ring
+<lwt_test/lwt_test.{native,byte}>: pkg_cstruct
+<lwt_test/lwt_test.{native,byte}>: pkg_cstruct.syntax
 <lwt_test/lwt_test.{native,byte}>: pkg_lwt
+<lwt_test/lwt_test.{native,byte}>: pkg_lwt.syntax
 <lwt_test/lwt_test.{native,byte}>: pkg_lwt.unix
 <lwt_test/lwt_test.{native,byte}>: pkg_oUnit
-<lwt_test/lwt_test.{native,byte}>: pkg_lwt.syntax
-<lwt_test/lwt_test.{native,byte}>: pkg_cstruct
-<lwt_test/lwt_test.{native,byte}>: pkg_cstruct.syntax
-<lwt_test/*.ml{,i}>: use_lwt_shared_memory_ring
-<lwt_test/*.ml{,i}>: use_shared_memory_ring
+<lwt_test/lwt_test.{native,byte}>: use_lwt_shared_memory_ring
+<lwt_test/lwt_test.{native,byte}>: use_shared_memory_ring
+<lwt_test/*.ml{,i}>: pkg_cstruct
+<lwt_test/*.ml{,i}>: pkg_cstruct.syntax
 <lwt_test/*.ml{,i}>: pkg_lwt
+<lwt_test/*.ml{,i}>: pkg_lwt.syntax
 <lwt_test/*.ml{,i}>: pkg_lwt.unix
 <lwt_test/*.ml{,i}>: pkg_oUnit
-<lwt_test/*.ml{,i}>: pkg_lwt.syntax
-<lwt_test/*.ml{,i}>: pkg_cstruct
-<lwt_test/*.ml{,i}>: pkg_cstruct.syntax
+<lwt_test/*.ml{,i}>: use_lwt_shared_memory_ring
+<lwt_test/*.ml{,i}>: use_shared_memory_ring
 <lwt_test/lwt_test.{native,byte}>: custom
 # Executable client
-<examples/client.{native,byte}>: use_lwt_shared_memory_ring
-<examples/client.{native,byte}>: use_shared_memory_ring
-<examples/client.{native,byte}>: pkg_lwt
-<examples/client.{native,byte}>: pkg_lwt.unix
-<examples/client.{native,byte}>: pkg_lwt.syntax
 <examples/client.{native,byte}>: pkg_cstruct
 <examples/client.{native,byte}>: pkg_cstruct.syntax
-<examples/*.ml{,i}>: use_lwt_shared_memory_ring
-<examples/*.ml{,i}>: use_shared_memory_ring
-<examples/*.ml{,i}>: pkg_lwt
-<examples/*.ml{,i}>: pkg_lwt.unix
-<examples/*.ml{,i}>: pkg_lwt.syntax
+<examples/client.{native,byte}>: pkg_lwt
+<examples/client.{native,byte}>: pkg_lwt.syntax
+<examples/client.{native,byte}>: pkg_lwt.unix
+<examples/client.{native,byte}>: use_lwt_shared_memory_ring
+<examples/client.{native,byte}>: use_shared_memory_ring
 <examples/*.ml{,i}>: pkg_cstruct
 <examples/*.ml{,i}>: pkg_cstruct.syntax
+<examples/*.ml{,i}>: pkg_lwt
+<examples/*.ml{,i}>: pkg_lwt.syntax
+<examples/*.ml{,i}>: pkg_lwt.unix
+<examples/*.ml{,i}>: use_lwt_shared_memory_ring
+<examples/*.ml{,i}>: use_shared_memory_ring
 <examples/client.{native,byte}>: custom
 # OASIS_STOP
 true: annot

diff --git a/lib/META b/lib/META
@@ -1,6 +1,6 @@
 # OASIS_START
-# DO NOT EDIT (digest: 85d83ee391f70fe17b5e0f90efb80b00)
-version = "1.0.0"
+# DO NOT EDIT (digest: 048e1d594c064f1cc44da25fc1042dfe)
+version = "1.1.0"
 description = "Xen-style shared memory rings"
 requires = "cstruct cstruct.syntax"
 archive(byte) = "shared_memory_ring.cma"
@@ -9,7 +9,7 @@ archive(native) = "shared_memory_ring.cmxa"
 archive(native, plugin) = "shared_memory_ring.cmxs"
 exists_if = "shared_memory_ring.cma"
 package "xenstore" (
- version = "1.0.0"
+ version = "1.1.0"
  description = "Xen-style shared memory rings"
  requires = "shared-memory-ring"
  archive(byte) = "xenstore_ring.cma"
@@ -20,7 +20,7 @@ package "xenstore" (
 )
 
 package "lwt" (
- version = "1.0.0"
+ version = "1.1.0"
  description = "Xen-style shared memory rings"
  requires = "shared-memory-ring lwt lwt.syntax"
  archive(byte) = "lwt_shared_memory_ring.cma"
@@ -31,7 +31,7 @@ package "lwt" (
 )
 
 package "console" (
- version = "1.0.0"
+ version = "1.1.0"
  description = "Xen-style shared memory rings"
  requires = "shared-memory-ring"
  archive(byte) = "console_ring.cma"

diff --git a/lib/ring.ml b/lib/ring.ml
@@ -327,6 +327,9 @@ module type S = sig
   module Reader: READABLE
   module Writer: WRITABLE
 
+  val write: Cstruct.t -> string -> int -> int -> int
+  val read: Cstruct.t -> string -> int -> int -> int
+
   val unsafe_write: Cstruct.t -> string -> int -> int -> int
   val unsafe_read: Cstruct.t -> string -> int -> int -> int
 end
@@ -397,15 +400,15 @@ module Pipe(RW: RW) = struct
   end
 
   (* Backwards compatible string interface: *)
-  let unsafe_read t buf ofs len =
+  let read t buf ofs len =
     let seq, frag = Reader.read t in
     let data_available = Cstruct.len frag in
     let can_read = min len data_available in
     Cstruct.blit_to_string frag 0 buf ofs can_read;
     Reader.advance t Int32.(add seq (of_int can_read));
     can_read
 
-  let unsafe_write t buf ofs len =
+  let write t buf ofs len =
     let seq, frag = Writer.write t in
     let free_space = Cstruct.len frag in
     let can_write = min len free_space in
@@ -419,8 +422,13 @@ module Pipe(RW: RW) = struct
     then n + (repeat f from buf (ofs + n) (len - n))
     else n
 
-  let unsafe_read = repeat unsafe_read
-  let unsafe_write = repeat unsafe_write
+  let read = repeat read
+  let write = repeat write
+
+  (* These are provided for backwards compat. Note they used to be unsafe
+     but are now safe (see #10) *)
+  let unsafe_read = read
+  let unsafe_write = write
 end
 
 module type Bidirectional_byte_stream = sig

diff --git a/lib/ring.mli b/lib/ring.mli
@@ -194,6 +194,20 @@ module type S = sig
   module Reader: READABLE
   module Writer: WRITABLE
 
+  (* These functions are suitable if you don't need to reconnect after a crash
+     and you don't mind always copying into strings.
+     If you do need to reconnect or need to avoid copying, use the READER and
+     WRITABLE signatures above *)
+
+  val write: Cstruct.t -> string -> int -> int -> int
+  (** [write stream buf ofs len] writes up to [len] bytes from [buf] at [ofs]
+      to [stream]. If this returns short it means EOF *)
+
+  val read: Cstruct.t -> string -> int -> int -> int
+  (** [read stream buf ofs len] reads up to [len] bytes to [buf] at [ofs] from
+      [stream]. If this returns short it means EOF *)
+
+  (* These functions are deprecated (and nolonger unsafe, see #10) *)
   val unsafe_write: Cstruct.t -> string -> int -> int -> int
   val unsafe_read: Cstruct.t -> string -> int -> int -> int
 end