minor orb stuff

[polintos/scott/priv.git] / doc / orb / marshalling

diff --git a/doc/orb/marshalling b/doc/orb/marshalling
index ab429bb8e853ee0e27a0e02154c8dbb6ff96f98b..e56e350a0d3eebc3c991906f4ad856a9112fc42c 100644 (file)
--- a/doc/orb/marshalling
+++ b/doc/orb/marshalling
@@ -37,6 +37,26 @@ for 32-bit architectures and 32 for 64-bit architectures.
 Object references are encoded as pointer-sized offsets into the
 objlist array.
 
+Virtual structs are prefaced with a header, which consists of
+the following, in order:
+1. 128-bit GUID of the most derived vstruct type
+2. 160-bit SHA-1 of the vstruct type info
+3. 32-bit objlist-offset of an introspection object
+4. 32-bit length of vstruct, including header, and all referenced
+data chunks, which must be contiguously appended to the vstruct body
+5. 32-bit reserved field
+
+The requirement for all referenced data chunks to be contiguous with
+the vstruct means that scatter-gather and zero-copy cannot be done;
+however, it prevents the loss of derived-type data when only a base
+type is known at unmarshalling time (the derived-type data could
+later be accessed through introspection, or be passed to another
+process that does know the derived type).  For this reason, vstructs
+should generally not be used to pass large chunks of data.
+
+The introspection object reference may be NULL; in this case, the
+SHA-1 field is ignored.
+
 Op1: Get Interface List
 -----------------------