From df68e916c45940dbddbf321fe77dc794f5395efe Mon Sep 17 00:00:00 2001 From: Alain Frisch Date: Wed, 23 Apr 2014 16:04:02 +0000 Subject: #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 --- stdlib/marshal.mli | 31 ++++++++++++++++++++----------- 1 file 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]] -- cgit v1.2.1