Add Functional Programming - Stateful Types

Author: jhwgh1968

SUMMARY.md

@@ -44,6 +44,7 @@
 
 - [Functional Programming](./functional/index.md)
   - [Programming paradigms](./functional/paradigms.md)
+  - [Stateful Types: Generics as Type Classes](./functional/stateful-types.md)
 
 - [Additional Resources](./additional_resources/index.md)
   - [Design principles](./additional_resources/design-principles.md)

functional/stateful-types.md

@@ -0,0 +1,247 @@
+# Stateful Types: Generics as Type Classes
+
+## Description
+
+Rust's functional roots allow for it to be more expressive in the type system
+than many other languages, and turn many kinds of programming problems into
+"static typing" problems. A key part of this idea is the way generic types work.
+
+In C++ and Java, for example, generic types a meta-programming construct for the
+compiler. A `Vec<int>` and `Vec<char>` in C++ are just two different copies of
+the same boilerplate code for a `Vec` type, with two different types filled in.
+
+In Rust, the generic type parameter creates what is known as a "type class", and
+each value used by an end user *actually changes the type of each instatiation*.
+In other words, `Vec<usize>` and `Vec<char>` *are two different types*.
+
+This is why `impl` blocks must specify generic parameters: different ones can
+have different `impl` blocks on them.
+
+It is recommended in rust to use generic types to enforce invariants. The best
+example is a state machine.
+
+## Example
+
+Suppose you are designing an interpreted language runtime, which requires a JIT
+compiler in order to process. Many Rust novices coming from other languages
+would implement it this way:
+
+```rust
+#[derive(Debug)]
+pub enum CompileError {
+    // error type, std::error::Error impl skipped for brevity
+}
+
+#[derive(Debug)]
+pub enum ExecError {
+    // error type, std::error::Error impl skipped for brevity
+}
+
+pub type ExecutionResult = Result<(), ExecError>;
+
+pub type CompileResult = Result<(), CompileError>;
+
+pub enum Param {
+    GCSize(usize),
+    MaxStack(usize),
+    // more parameters...
+}
+
+#[derive(Default)]
+pub struct Interpreter {
+    // state and execution data
+}
+
+impl Interpreter {
+    /// Set a system prameter.
+    ///
+    /// # Panics
+    /// Will panic if called after a script is executed.
+    ///
+    pub fn set_param(&mut self, p: Param) {
+        /* update the state based on the parameter */
+    }
+
+    /// Set up a new execution environment.
+    ///
+    /// # Panics
+    /// Will panic if called more than once or after a script has been compiled.
+    ///
+    pub fn init(&mut self) {
+        /* Create the heap, prepare for use... */
+    }
+
+    /// Load and compile a script. Returns any errors encountered.
+    ///
+    pub fn compile_script(&mut self, script: &str) -> CompileResult {
+        /* actually do the compile... */
+        Ok(())
+    }
+
+    /// Execute all scripts added. Returns any errors encountered.
+    ///
+    /// # Panics
+    /// Will panic if zero scripts have been compiled.
+    ///
+    pub fn exec(&mut self) -> ExecutionResult {
+        /* actually run the script... */
+        Ok(())
+    }
+}
+
+fn main() {
+    let mut interp = Interpreter::default();
+    interp.set_param(Param::GCSize(1024 * 1024 * 1024));
+    interp.init();
+    interp.compile_script("print('2 + 2')").unwrap();
+    interp.exec().unwrap();
+}
+```
+
+Why those chances to panic? Because there are *state invariants* here:
+
+1. `set_param` can only be called in an "initial" state.
+1. `init` must be called before any scripts are compiled.
+1. `exec` can only be called in a "loaded" or "ready" state.
+1. `init` must be called *exactly once*.
+
+It would be possible to add these to the `Error` types instead of panicking.
+However, this solution is suboptimal. Not only would users of the code
+correctly have to `unwrap()` a result all the time, but the requirement to call
+init exactly once is still unenforcable across an entire program without
+additional state (like `called = true` in the struct).
+
+What would really be neat is if it were possible to create a compile-time error
+if it were misused. After all, every user's program contains the invalid call
+order in the logic itself.
+
+In Rust, this is actually possible! The solution is to *change the type* in
+order to enforce the invariants. How? With a private generic parameter.
+
+Here is what that looks like:
+
+```rust,ignore
+// this is a module to prevent users outside this crate from doing their own impls
+mod state_trait {
+    pub(crate) trait State {}
+
+    pub(crate) struct Init {
+        params: Vec<Param>,
+    }
+    impl State for Init {}
+
+    pub(crate) struct Loaded {
+        scripts: Vec<CompiledScript>,
+    }
+    impl State for Loaded {}
+
+    pub(crate) struct Ready(Vec<CompiledScript>);
+    impl State for Ready {}
+}
+use state_trait::*;
+
+
+struct Interpreter<S: State> {
+    // same fields for execution, but now add:
+    state_data: S,
+}
+
+impl Default for Interpreter<Init> {
+    /* impl does the same thing the old default one did */
+}
+
+impl Interpreter<Init> {
+    /// Set a system prameter.
+    ///
+    /// # Panics
+    /// Will panic if called after a script is executed.
+    ///
+    pub fn set_param(&mut self, p: Param) {
+        /* update the state based on the parameter */
+    }
+
+    /// Initialize this intepreter, disallowing more parameter sets.
+    ///
+    pub fn init(self) -> Interpreter<Loaded> {
+        /* copy all of the parameters into self's members... */
+
+        // return our new initialized interpreter
+        Interpreter {
+            state_data: Loaded { scripts: vec![] },
+            // copy other fields...
+        }
+    }
+}
+
+impl Interpreter<Loaded> {
+    /// Load and compile a script. Returns any errors encountered.
+    ///
+    pub fn compile_script(&mut self, script: &str) -> CompileResult {
+        /* actually do the compile... */
+        Ok(())
+    }
+
+    // Indicates we are done compiling scripts.
+    pub fn ready(self) -> Interpreter<Ready> {
+        /* prepare to actually execute scripts... */
+
+        Interpreter {
+            state_data: Ready(),
+            // copy other fields...
+        }
+    }
+}
+
+impl Interpreter<Ready> {
+    /// Execute all scripts added. Returns any errors encountered.
+    ///
+    /// # Panics
+    /// Will panic if no scripts had been compiled.
+    ///
+    pub fn exec(&mut self) -> ExecutionResult {
+        /* actually run the script... */
+        Ok(())
+    }
+
+    /// Returns to a state where more scripts can be loaded.
+    pub fn reset(self) -> Interpreter<Loaded> {
+        /* clean up any state as needed... */
+
+        Interpreter {
+            state_data: Loaded(self.0),
+            // copy other fields...
+        }
+    }
+}
+```
+
+With this approach, if the user were to make a mistake and set a parameter
+after init:
+
+```rust,ignore
+fn main() {
+    let mut interp = Interpreter::<Init>::default().init();
+    interp.set_param(Param::GCSize(1024 * 1024 * 1024);
+}
+```
+
+They would get a syntax error. The type `Interpreter<Loaded>` does not
+implement set param, only the type `Interpreter<Init>` does.
+
+## Disadvantages
+
+This is a lot of typing. Depending on the amount of change caused by state
+transitions, an `InvalidState` enum value in an error type might be simpler.
+
+## Alternatives
+
+There are a number of simpler state machines, however, that have their own patterns:
+
+1. If the state transition is during construction/finalizing of an object, see [Builder Pattern](../patterns/creational/builder.md).
+1. If the state transitions don't change invariants much, see [Strategy Pattern](../patterns/behavioural/strategy.md).
+
+## See also
+
+* [The Case for the Type State Pattern](https://www.novatec-gmbh.de/en/blog/the-case-for-the-typestate-pattern-the-typestate-pattern-itself/)
+* FIXME: I remember seeing a Rust talk which described this in more detail, but I
+can't find it again.