docs: (very) draft notes on effects systems and interop

2 files changed, 47 insertions, 0 deletions

diff --git a/docs/EFFECTS.md b/docs/EFFECTS.md
new file mode 100644
index 0000000..aef1a6c
--- /dev/null
+++ b/docs/EFFECTS.md
@@ -0,0 +1,15 @@
+# Effects
+
+I don't know enough about effects to get started with this section.
+
+Existing systems to learn from:
+- https://koka-lang.github.io/koka/doc/index.html
+- https://effekt-lang.org/
+- https://github.com/zesterer/tao
+- https://v2.ocaml.org/manual/effects.html
+- https://www.stephendiehl.com/posts/exotic03.html
+- https://github.com/ocaml-multicore/ocaml-effects-tutorial
+- https://blog.poisson.chat/posts/2023-01-02-del-cont-examples.html
+- https://arxiv.org/abs/1807.05923
+
+Effects are common "impure" operations that disrupt the regular flow of a language / function. Things like exceptions, async, & IO and "handlers" for such can all be captured into an effects system. Effect systems are in an active state of development: by far their hardest problem is *syntactic*, however. How much information is okay to expose to the user? How much is helpful?
diff --git a/docs/INTEROP.md b/docs/INTEROP.md
new file mode 100644
index 0000000..805f747
--- /dev/null
+++ b/docs/INTEROP.md
@@ -0,0 +1,32 @@
+# Interop with Other Languages
+
+A major goal of Puck is _universal, minimal-overhead language interoperability while maintaining type safety_.
+
+There are three issues that complicate language interop:
+1. Conflicting memory management systems, i.e. Boehm GC vs. reference counting
+2. Conflicting type systems, i.e. Python vs. Rust
+3. The C ABI.
+
+For the first, Puck uses what amounts to a combination of ownership and reference counting: and thus it is exchangeable in this regard with Nim (same system), Rust (ownership), Swift (reference counting), and many others. (It should be noted that ownership systems are broadly compatible with reference counting systems).
+
+For the second, Puck has a type system of similar capability to that of Rust, Nim, and Swift: and thus interop with those languages should be straightforward for the user. Its type system is strictly more powerful than that of Python or C, and so interop requires additional help. Its type system is equally as powerful as but somewhat orthogonal to Java's, and so interop is a little more difficult.
+
+For the third, Puck is being written at the same time as the crABI ABI spec is in development. crABI promises a C-ABI-compatible, cross-language ABI spec, which would *dramatically* simplify the task of linking to object files produced by other languages. It is being led by the Rust language team, and both Nim and Swift have expressed interest in it. Which bodes quite well for future...
+
+Languages often focus on interop from purely technical details. This *is* very important: but typically no thought is given to usability (and often none can be, for necessity of compiler support), and so using foreign function interfaces very much feel like using *foreign* interfaces. Puck attempts to change that.
+
+...todo...
+
+Existing systems to learn from:
+- https://doc.rust-lang.org/reference/abi.html
+- https://www.hobofan.com/rust-interop/
+- https://github.com/eqrion/cbindgen
+- https://github.com/chinedufn/swift-bridge
+- https://kotlinlang.org/docs/native-c-interop.html
+- https://github.com/crackcomm/rust-lang-interop
+- https://doc.rust-lang.org/reference/abi.html
+- https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier
+- https://github.com/yglukhov/nimpy
+- https://github.com/yglukhov/jnim
+- https://github.com/PMunch/futhark
+- https://lib.haxe.org/p/callfunc/