More WIP how it works

Author: williamhaarhoff

docs/how_it_works.md

@@ -3,8 +3,127 @@
 
 This document is meant to clearly show the principles on which archetype works without you having to decipher the macro heavy archetype.h file. The intention is to show how the principles have been combined, and provide a rationale for why I have implemented archetype this way. 
 
-Underneath the hood Archetype uses manual vtables to acheive type erasure and run time polymorphism. This is not dissimilar from how virtual functions in traditional inheritance work. Vtables and surrounding infrastructure require a lot of boiler plate. The point of Archetype is to automate manual vtable generation, in a modular/composable way.
+Underneath the hood `Archetype` uses manual vtables to acheive type erasure and run time polymorphism. This is not dissimilar from how virtual functions in traditional inheritance work. Vtables and surrounding infrastructure require a lot of boiler plate. The point of `Archetype` is to automate manual `vtable` generation, in a modular/composable way.
 
+### The basic vtable 
+A `vtable` is a structure containing free function pointers (non member function pointers). For example, this is a `vtable` structure containing function pointers for `func_a` and `func_b`.
+
+```cpp
+struct vtable
+{
+  int (*func_a)(int);
+  float (*func_b)(float);
+};
+```
+We can now assign any function that matches this signature to the vtable. For example:
+
+```cpp
+int func_a(int a) { return a + 5; }
+float func_b(float b) { return b + 5.3; }
+
+vtable mytable;
+mytable.func_a = &func_a;
+mytable.func_b = &func_b;
+```
+we can now call these functions through the vtable:
+```cpp
+mytable.func_a(5);    //returns 10;
+mytable.func_b(5.f);  //returns 10.3;
+```
+### The object facing vtable
+In Archetype the goal is binding objects/classes, not free functions. Member function pointers (non static) are not free functions. They have to point to both the correct function, and the object instance, which mean they don't have the size of a free function pointer.
+
+Lets say we want a vtable that can call objects of the following type:
+```cpp
+struct A
+{
+  int func_a(int a) { return a + internal_int++; }
+  float func_b(float b) { return b + (internal_float += 1.3f); }
+  int internal_int = 5;
+  int internal_float = 5.3;
+};
+```
+
+We can get around this by storing free functions that can be called with an object pointer. For example our vtable becomes:
+
+```cpp
+struct vtable
+{
+  int (*func_a)(A *, int);
+  float (*func_b)(A *, float);
+};
+```
+We can then assign this vtable to call an object of type `A's` functions. 
+```cpp
+A obj;
+vtable vtbl;
+vtbl.func_a = [](A * ptr, int a) { return ptr->func_a(a); };
+vtbl.func_b = [](A * ptr, float b) { return ptr->func_b(b); };
+
+vtbl.func_a(obj, 5);    // call func_a on obj
+vtbl.func_b(obj, 6.4);  // call func_b on obj
+```
+
+This implementation is not very generic. As our vtable depends on type A. We can make the vtable type agnostic by passing in the object as a void pointer instead. We can push the type specific handling into the lambda. 
+
+```cpp
+struct vtable
+{
+  int (*func_a)(void *, int);
+  float (*func_b)(void *, float);
+};
+
+vtbl.func_a = [](void * ptr, int a) { 
+  return static_cast<A*>(ptr)->func_a(a); 
+};
+
+vtbl.func_a(static_cast<void*>(obj), 5);
+```
+
+### The view
+So far the vtable itself has given us a type erased way to call functions on arbitrary types, provided we can assign lambdas to out vtable function pointers. However, its still very awkward to setup and call. The `view` is an object that carries around the object `void *` and can pass this into the vtable functions.
+
+```cpp
+struct view
+{
+  int func_a(int a) { return vtbl_->func_a(obj_, a); }
+  float func_b(float b) { return vtbl_->func_b(obj_, b); }
+  void * obj_;
+  vtable * vtbl_;
+};
+```
+Provided our vtable pointer is pointing to a vtable that is correct for the current type, then we can assign the object and call like so:
+
+```cpp
+A obj;
+view myview;
+myview.obj_ = static_cast<void*>(&obj);
+myview.vtbl_ = vtbl; // vtable for A
+
+myview.func_a(5);
+myview.func_b(3.2);
+```
+
+This is a little cleaner. We have one vtable instance per bound type. And we have one view instance per object that we bind to. By keeping the vtable and view separate as separate objects we keep memory usage lower, and have improved cache locality for the function pointers. 
+
+To ensure we are only creating on vtable per type, we can make use of a static vtable variable within a templated function. Every time we call `make_vtable<A>()` we are using a pointer to the `A` `vtable`.
+
+```cpp
+template <typename T>
+static vtable * make_vtable()
+{
+  static vtable vtablet;
+  vtablet.func_a = [](void * obj, int arg0) -> int {
+    return static_cast<T*>(obj)->write(arg0);
+  };
+  ...
+  return &vtablet;
+}
+```
+To handle function overloading we need to make sure that the `vtable` uses unique names for its function pointers. We can use normal function overloading in the view to resolve the correct function call.
+
+### The Archetype
+Taking inspiration from the way that C++20 concepts can be defined and composed together, I wanted to do something similar. The idea being that you could define interface specifications, and then compose these together. Below is the rough idea for a structure that defines the `writable` "concept". I ended up calling these containing structures Archetypes.  
 
 ```cpp
 struct writable
@@ -42,29 +161,98 @@ struct writable
 };
 ```
 
-Making it composable:
+To create views to types `A` and `B` we can do the following:
 
 ```cpp
-struct VTableBase {
+A a; B b; B b2; 
+writable::view view_a = writable::make_view(a);
+writable::view view_b = writable::make_view(b);
+writable::view view_b2 = writable::make_view(b2);
+```
+Both `view_b` and `view_b2` are using the same vtable to type `B`.
 
-  template<typename T>
-  static VTableBase * make_vtable() {
-    static VTableBase vtablet;
-    return &vtablet;
-  }
 
-  template <typename T>
-  void bind() {}
+### The composable vtable
+
+Lets say we also have a `readable` `Archetype`, and we would like to compose this together with `writable` to create `readwritable`. The resulting vtable and view should end up being:
+
+```cpp
+struct readwritable
+{
+  struct vtable 
+  {
+    int (*write)(void * obj, const char *, int); // from writable
+    int (*read)(void * obj, char *, int);        // from readable
+  };
+
+  struct view
+  {
+    void * obj;                                  // from ?
+    vtable * vtbl;                               // from ?
+    int write(const char * arg0, int arg1) { 
+      return vtbl->write(obj, arg0, arg1);       // from writable
+    }
+    int read(char * arg0, int arg1) { 
+      return vtbl->read(obj, arg0, arg1);        // from readable
+    }
+  };
+  ...
+};
+```
+
+I did this by orthogonalising the structures, and then composing them through inheritance of orthogonal parts. The orthogonal parts come from each of the existing archetypes, while the common parts can come from a common base.
+
+#### The composable vtable
+```cpp
+
+struct VTableCommonBase { }; // common base is empty as no common parts
+
+// view table layer for writable 
+template<typename BaseVTable = VTableCommonBase>
+struct write_vtlayer : public BaseVtable
+{
+  int (*write)(void * obj, const char *, int);
+};
+
+// view table layer for readable
+template<typename BaseVTable = VTableCommonBase>
+struct read_vtlayer : public BaseVtable
+{
+  int (*read)(void * obj, char *, int);
 };
+```
+We can still create our normal readable and writable vtables as:
+
+```cpp
+write_vtlayer<> wvtl; 
+write_vtlayer<> rvtl; 
+```
+We can now compose our inheritance chain for the readwritable vtable as:
+
+```cpp
+template<typename BaseVTable = VTableCommonBase>
+struct readwrite_vtable_layer 
+: public write_vtlayer<read_vtlayer<BaseVtable>> // inheritance chain
+{};
+```
+
+#### The composable view
+We end up doing the same thing for the view. Except we have a common object, and vtable pointer, which gets placed in the common base. 
 
+```cpp
 template<typename VTableType>
 struct ViewBase
 {
   void * _obj;
   VTableType * _vtbl;
 };
+```
+
 
 
+
+
+```
 struct writable
 {
   template<typename BaseVTable = VTableBase>