document learnings

doc/dev-learnings.kk.md

@@ -0,0 +1,17 @@
+# What Tim Learned Designing LibUV
+
+- Autogenerated bindings are a good idea (they are less work to maintain, more consistent and less error prone)
+- However, they lack the flexibility of hand-written bindings (including some marginal efficiency gain in rare cases)
+- In particular for synchronous APIs (like the filesystem API when you do not provide a callback), 
+we can use stack allocated `uv_fs_req` objects.
+It would be require more work on the compiler to do the same and make the guarantees we need to not escape the stack.
+- Additionally autogenerated bindings typically end up with a large file, which often takes a while to compile. Not sure if that is partially due to the C compiler instead of the Koka compiler.
+- Most apis with callbacks require us to define a
+callback function in C for the binding anyways.
+To do the same from Koka we would need a specialized type signaling to the compiler to emit a c callback wrapper function without a `kk_context_t` parameter for us. (Getting the `kk_context` instead from the thread local variable). I believe these sorts of functions are called trampolines. The trampoline also needs to know how to get data from it's environment (like the `uv_fs_req` object) to call the appropriate Koka closure, and we need to set it beforehand.
+- Handle types differ from request types in that they are long lived, and their callbacks can be called multiple times. Currently this is awkward in some cases when managing memory (from Koka). The handwritten bindings have less of a problem here.
+- We should really merge something like (https://github.com/koka-lang/koka/pull/494) for strongly typing external objects, and allowing those external objects to be reference counted and managed by Koka.
+- When managing stream like objects that also require state or buffering, a named handler works rather well.
+- We really could use conditional imports for different platforms. Especially needed if we want to support autogenerated bindings, without having to create stubs in all of the externs for wasm for example.
+- Most bindings don't require many complicated types or conversions, and so we can get away with simple extern definitions. Most types can be interacted with solely via abstraction (opaque pointers), and
+the interface in (https://github.com/koka-lang/koka/pull/494) is needed for that. More to the point however, we need a really robust and performant bytes and string buffer library. I wouldn't complain about string interpolation as well.