#6119: document that the set of values contained in a closure is not specified and how this impacts marshaling references captured in closures, for instance.

git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@14670 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02

1 files changed, 20 insertions, 11 deletions

diff --git a/stdlib/marshal.mli b/stdlib/marshal.mli
index ac39a6bd4a..1ab15230cb 100644
--- a/stdlib/marshal.mli
+++ b/stdlib/marshal.mli
@@ -74,17 +74,26 @@ val to_channel : out_channel -> 'a -> extern_flags list -> unit
    byte representations if [v] actually contains sharing,
    or even non-termination if [v] contains cycles.
 
-   If [flags] does not contain [Marshal.Closures],
-   marshaling fails when it encounters a functional value
-   inside [v]: only 'pure' data structures, containing neither
-   functions nor objects, can safely be transmitted between
-   different programs. If [flags] contains [Marshal.Closures],
-   functional values will be marshaled as a position in the code
-   of the program. In this case, the output of marshaling can
-   only be read back in processes that run exactly the same program,
-   with exactly the same compiled code. (This is checked
-   at un-marshaling time, using an MD5 digest of the code
-   transmitted along with the code position.)
+   If [flags] does not contain [Marshal.Closures], marshaling fails
+   when it encounters a functional value inside [v]: only 'pure' data
+   structures, containing neither functions nor objects, can safely be
+   transmitted between different programs. If [flags] contains
+   [Marshal.Closures], functional values will be marshaled as a the
+   position in the code of the program together with the values
+   corresponding to the free variables captured in the closure.  In
+   this case, the output of marshaling can only be read back in
+   processes that run exactly the same program, with exactly the same
+   compiled code. (This is checked at un-marshaling time, using an MD5
+   digest of the code transmitted along with the code position.)
+
+   The exact definition of which free variables are captured in a
+   closure is not specified and can very between bytecode and native
+   code (and according to optimization flags).  In particular, a
+   function value accessing a global reference may or may not include
+   the reference in its closure.  If it does, unmarshaling the
+   corresponding closure will create a new reference, different from
+   the global one.
+
 
    If [flags] contains [Marshal.Compat_32], marshaling fails when
    it encounters an integer value outside the range [[-2{^30}, 2{^30}-1]]