mojo: MessageBuilder

mojo/ipc/message/README

Index: mojo/ipc/message/README
diff --git a/mojo/ipc/message/README b/mojo/ipc/message/README
new file mode 100644
index 0000000000000000000000000000000000000000..abf41e44e4aeb751bb88cc6f12739b707744da0c
--- /dev/null
+++ b/mojo/ipc/message/README
@@ -0,0 +1,33 @@
+MESSAGE FORMAT
+==============
+
+A Mojo IPC message resembles a property bag, with ordinals as property names.
+
+Message:
+  [ MessageName | MessageSize | Field_1 | Field_2 | ... | Field_N ]
+
+MessageName:
+  [ U32 ]
+
+MessageSize:
+  [ U32 ]
+
+Field:
+  [ FieldHeader | FieldValue ]
+
+FieldHeader:
+  [ FieldName | FieldType ]
+
+FieldName:
+  [ U16 ]
+
+FieldType:
+  [ U16 ]

[vtl, 2013/09/12 01:16:10]

Another thought occurred to me: Maybe we should steal a few bits from this and
encode the size?

E.g., take 2 bits and have them mean:

00 - 0 bytes
01 - 4 bytes
10 - 8 bytes
11 - size specified by FieldSize

(obviously, taking 3 bits gives you a bit more flexibility).

The advantage is forwards-compatibility, so that you can skip fields whose
FieldTypes that you don't know about.

+
+FieldValue:
+  [ U32 ]

[vtl, 2013/09/11 17:37:16]

I guess by "U32" here, you mean any 32 bits of data (per FieldType). Which I
guess also implies that chars, bools, int16_ts, etc. all get padded out to 32
bits (which I guess is fine), right?

+  [ U64 ]

[vtl, 2013/09/11 17:37:16]

Is there any desire to have 64-bit quantities be aligned (on 8-byte boundaries)?

If added <empty> as a possible FieldValue, we could reserve FieldName=0,
FieldType=0 as an empty padding field. (We could also do some optimizations,
e.g., optimize bools by having separate "bool_true" and "bool_false"
FieldTypes.)

+  [ FieldSize | FieldBytes ]

[vtl, 2013/09/11 17:37:16]

Similarly, do we want to insist that FieldBytes be padded out to a multiple of 4
bytes?

+

[vtl, 2013/09/11 17:37:16]

It occurs to me that we want to assign ordinals to passed handles also. Should
this be done by adding data to the message data itself (e.g., a handle
FieldType, with the FieldValue indicating the index in the array of handles) or
separately?

(I favor the former, since it keeps the message serialization format separate
from the transport primitives.)

+FieldSize:
+  [ U32 ]