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,227 @@
+# 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
+
+FIXME: I looked through several papers on functional languages, but they are all too abstract and none of them describe this specifically. Any suggestions?
+
+FIXME: I remember seeing a Rust talk which described this in more detail, but I can't find it again.