First crack at spec'ing REPR compose protocol.

Author: jnthn

docs/6model/repr-compose-protocol.markdown

@@ -0,0 +1,98 @@
+# REPR Compose Protocol
+
+In 6model, representations take responsibility for memory layout, while a
+meta-object is responsible for other aspects of type-ness (dispatch, type
+checking, etc.) Typically, meta-objects are at some point "composed" - that
+is, they reach a point where the definition of the type they represent is
+either closed or complete in some sense. Certain representations need to be
+(or in some cases, may be) configured. For example, a representation that does
+efficient storage of an object's attributes needs configuring with information
+about the things it should store. This configuration happens through the REPR
+composition protocol. The meta-object uses the nqp::composetype primitive in
+order to do this.
+
+The protocol is defined entirely in terms of arrays and hashes. Why? So we
+don't have to define a particularly complex object system in order to define
+an object system. :-) At the top level, a hash is always passed. Its keys
+indicate the configuration for a specific part of the protocol, the the values
+are a data structure providing the appropriate information.
+
+The rest of this documentation describes these protocols; each heading is a
+key that can appear in the top level hash, and what's below it indicates what
+should fall beneath those keys.
+
+## attribute
+
+The value is an array with one element for each entry in the MRO, from most
+derived to least derived. Each element is in turn an array, consisting of 3
+elements:
+
+* The type object of the type at this point in the MRO
+* An array of hashes, each hash describing an attribute
+* The immediate parents, if any, of the type object in question
+
+The hash describing an individual attribute must have the following keys:
+
+* name - provides the name of the attribute
+
+It may optionally have these keys:
+
+* type - type object specifying the type of the attribute. Note that this is
+  used purely for the purpose of allocation. It is NOT up to the REPR to do
+  type checks. Anything without this is assumed to be a reference type. In
+  fact, anything that's a reference type is uninteresting in terms of this
+  key since it just gets a reference to another object. It's native types or
+  other compact things that can be flattened into the object body that are
+  interesting.
+  
+* box_target - if this key is present, then this type is a target for boxing
+  or unboxing.
+  
+* auto_viv_container - if this key is present then an access to an attribute
+  that is uninitialized will cause that attribute to be set to a clone of the
+  value under this key. If the value is a type object, the clone will not take
+  place, since cloning a type object is meaningless.
+
+* positional_delegate - if this key is present, the given (reference type)
+  attribute will be delegated to if the positional part of the REPR API is
+  used with the object. This is primarily to support languages that need to
+  reasonably efficiently provide positional things that can also be mixed
+  in to in arbitrary ways.
+  
+* associative_delegate - the same as positional_delegate, for the associative
+  part of the REPR API.
+
+## integer
+
+A hash that may have the following keys:
+
+* bits - the number of bits. Which sizes are supported are up to the REPR.
+
+* unsigned - if this key exists, then the stored value is unsigned.
+
+## float
+
+A hash that may have the following keys:
+
+* bits - the number of bits. Which sizes are supported are up to the REPR.
+
+## array
+
+A hash that may have the following keys:
+
+* type - the type of the array attributes. While all reference types are
+  equivalent, native types will be inlined, leading to a compact array. A REPR
+  is free to decide what types it supports, and just because it is asked to be
+  an array of 1-bit ints in no way obligates it to use a bit of storage for
+  each element. Again, this is just about layout and lookup, not about type
+  checking.
+
+## hash
+
+* valuetype - the type of the hash value. As with arrays, it's up to the REPR
+  how or if it handles native types. Just about layout.
+
+* keytype - the type of the hash key. REPRs are likely to be restrictive here,
+  since they need to understand the representation of the provided key well
+  enough to hash it. This will probably mean strings and whatever REPR ObjAt
+  in Perl 6 (or some other language's variant) has.