This document summarizes the model of computation that the Swanson framework implements.
A Swanson program has to execute somewhere. This place is called the host. The Swanson execution model takes very great care to make no assumptions whatsoever about the host. The only real assumption is that the host somehow knows how to execute Swanson code! That might mean that it interprets it directly, or that there’s some compiled representation that can be executed, and which brings about the same effect as the Swanson program that was compiled. As long as the host can faithfully implement the execution model described here, we’re golden!
What kinds of hosts are we talking about? A “native” host would compile a Swanson program down to machine code, just like a C, Rust, Go, or Haskell compiler would, and then execute it directly. A “JVM” host would compile a Swanson program down to JVM bytecode, so that it could more easily interact with code written in Java. An “embedded interpreter” would implement the execution rules below as simply as possible, with no compilation or optimization. That would make the interpreter very simple, and make it easy to include it in another application written in some other language.
Note
A particular Swanson program is free to assume more about the host than just this. It would typically do so by depending on code that isn’t available on all hosts. (We talk about how you depend on other code below.) And if some of the code your program depends on isn’t available on some host, you can’t excute your program on that host!
There are certain behaviors that are considered “hard” errors. In a tradition that dates back to the early days of computing, we say that these errors cause the host to halt and catch fire (HCF).
The reason for this name is that some interpreted hosts will just blindly
execute the code that they’re given. If they encounter one of these erroneous
behaviors, the host will literally just stop executing. (In the current C host,
for instance, we use assert checks to verify that these situations don’t
occur, and abort the process if they do!)
Other hosts will take advantage of Swanson’s type system, which ensures that any well-typed program cannot possibly cause the host to halt and catch fire. This is most common in compiled hosts, where we have to transform the Swanson code into machine code or some other more directly executable representation. Since we’re already preprocessing the code, we might as well verify that the Swanson code is well-typed. By doing so, the resulting compiled code does not need to check for any HCF error conditions.
(Note that type-checking is not limited to compiled hosts; it’s perfectly acceptable for an interpreted host to type-check the Swanson code that it loads before executing it. The interpreter’s implementation would then similarly be able to avoid HCF checks.)
A Swanson program operates on an environment, which is a collection of values, each with a separate name. (A good intuition is that it’s the set of parameters and variables that are in scope at the current point of execution.)
Note
Names in Swanson are binary — they are a sequence of octets. When you translate a higher-level language into Swanson, you will use names to represent its identifiers, which will presumably be strings of characters. But Swanson is careful not to make any assumptions about what character set or encoding is used for those identifiers. It’s true that most languages these days use ASCII or UTF-8 to encode their identifiers, but that’s not a hard requirement.
There are only three kinds of values: atoms, literals, and invokables.
An atom is a basic entity that exists and can be compared for equality. Atoms are primarily used at compile-time, and let us determine or assert that two things (types, values, anything really) are “the same”.
A literal represents immutable binary content. Literals are the only constants available to a Swanson program.
Note
Swanson programs use literals to instantiate “real” constants of other types. To create a numeric constant, for instance, you’d typically create a literal whose (binary) content is the ASCII rendering of the desired numeric value, and then use an invokable to parse that binary literal into the internal representation of the numeric value. Because we have the ability to explicitly mark that code should execute at compile time, there’s typically no runtime cost incurred.
Everything else — runtime values, types, classes, functions — is represented by an invokable. An invokable consists of one or more branches, each with a name and a body, which is some executable Swanson code. An invokable will typically also contain some hidden state. (Note that does not necessarily mean mutable state!)
The main thing that you do to an invokable (as you might guess from its name) is that you invoke one of its branches. The current environment is “passed into” the invokable as its input, and execution proceeds with the body of the selected branch.
Note
Note that control never returns from an invokable! Invokables are like continuations. Invoking is one-way. Everything is a tail call.
That doesn’t mean that you can’t model something like “returning from a function”! You’ll have an invokable representing the function, and its single branch contains the body of the function. To “call” the function, you invoke its invokable. But instead of implicitly keeping track of a stack of function calls, you must explicitly pass in a continuation as one of the inputs. This continuation represents the call stack that gets constructed before calling the function. Inside the function’s invokable, it will invoke the continuation anywhere that control is returned to the caller.
This also means that invokables don’t really have “output values”. In Swanson, an “output” is really just the input that’s passed into the continuation when it’s invoked. Control flow always moves forward!
For typical values that you’d encounter in other languages (integers, strings, booleans, instances of classes, instances of algebraic data types), the invokable encapsulates together the value itself, along with all of the operations that you can perform on that value (each represented by a branch).
In languages that have a concept of pointers or references, the “thing pointed
to” and the “pointer” or “reference” are both represented by (different)
invokables. The “thing pointed to” will have a “create reference” operation as
one of its branches (corresponding with the & operator from C or Rust). The
“pointer” will have a “dereference” operation (corresponding with the *
operator).
Invokables are also used to represent the basic blocks in your program. The internal state represents any values that are closed over — local variables on the stack in a typical imperative language, or values captured in a closure in a functional language. This kind of invokable would typically have a single branch, representing the normal control flow of your program. But in a language that supports exceptions or JavaScript-style promises, there would be two — one branch to handle the “success” case, and one to handle the “error” case.
Most invokables are implemented as Swanson code. (Or more accurately, they’re implemented in S₀, which is the Swanson “assembly language” that we’ll learn about later, or in a language that can be compiled or translated into S₀.)
However, you’ll probably have noticed that, unlike other language runtimes, there aren’t any “real” types mentioned above. No specific integer types, no strings, no booleans, nothing like that. In Swanson, none of that is predefined. Instead, those are provided by dfn:primitives. A primitive is a special type of invokable that is provided by the host, instead of being implemented in Swanson itself.
Note
The Swanson execution model does not predefine any of these primitives. It doesn’t say which ones are available, what their names are, or how they work. That might seem to be a hard programming framework to program against! However, there is a “standard library” of primitives, which we’ll describe later. Most hosts provide most of the primitives in the standard library. So for all practical purposes, the set of primitives is predefined — just not here at the lowest level of the framework.
Environments and values are linear, which means that they must be used exactly once. That means two things: First, you cannot use a value more than once. Invoking an invokable, or using an atom or literal, consumes the value. Second, you must use every value. When a Swanson program finishes, the environment must be empty.
Note
Primitives are “magical” in the sense that they let you side-step linearity. For example, a host could provide a primitive for duplicating values that are safe to duplicate, and wouldn’t provide them for other values. Since there’s no way to duplicate values purely in Swanson, that means we can be sure that all Swanson code follows the rules provided by the host environment.
This will be a pattern that we encounter all the time: linearity exists to provide a base level of safety, and lets us reason about when things can and must occur, but there will be “escape hatches” provided by the host that let us break out of those shackles in carefully controlled, well-scoped ways.
If an invokable is consumed when you invoke it, that works really well to model something like a destructor: calling a value’s destructor really should “remove” it from the caller’s context, so that the caller can’t accidentually try to use the now-freed value. In this case, linearity provides a really nice answer to the “use after free” problem.
But how then do we model functions or methods that don’t consume their receiver? In Swanson, the invokable must “return back” the value to the caller, making it available for additional, later method calls. (You will usually have to construct a new invokable to represent the returned-back value, since the original was just consumed; we’ll see examples in later sections of how to do that.)
Note
This pattern — where invokables explicitly return back values that can be used again in other ways — means that the set of operations you can perform on a value can change over time! There’s no obligation that the value that’s returned back has the same set of available operations (that is, the same set of branches in the invokable) as the one that was passed in.
This lets us model things like Rust’s lifetimes, which say that you can’t drop a value when there are still open references to it somewhere. In Swanson, the Rust version of the “create reference” operation would both return the reference as a new invokable, and also change the set of available operations on the original value to prevent you from calling its “drop” operation. Dropping the reference would then reenable the “drop” operation on the original value.
The last piece of our execution model lets you “program in the large”, breaking up a large program into smaller pieces that you can write, test, and compile separately. Most programming languages provide some kind of facility for this: packages in Java, crates in Rust, translation units in C, packages in Go.
In Swanson, the primary unit of modularity is the unit. Each unit has a name, and can be loaded, producing a Swanson value. The host is responsible for determining how to locate a unit with a particular name, and for loading it.
Note
Loading a unit typically produces an invokable, where each branch defines one of the entities “exported” by the unit. But this isn’t a hard requirement — it’s perfectly fine for a unit to produce an atom or literal, though that wouldn’t really be very useful in practice.
Units can have dependencies, which are the other named units that this unit needs as part of its loading or execution. The host will take care of loading those dependencies first (ensuring that there are no circular dependencies), and providing them to the unit.
The entry point of a Swanson program is a unit that defines the main body
of the program. (This corresponds with the main function of a C, Rust, Go,
or Java program.) An entry point unit, when loaded, must produce an invokable
with a single branch. The host will invoke this branch to execute the program.
Like any other unit, this entry point can (and almost certainly will) have
dependencies on other units, which it will use to do useful work.
Note
A unit can be loaded multiple times — once for each time it’s used as a dependency. Unlike other frameworks, we don’t “cache” the unit’s value and return it multiple times, since that would violate linearity! When a unit is loaded, the value that’s produced can only be used once. If the unit is used as a dependency multiple times, each of those dependents must end up with distinct values to obey linearity. That, in turn, means that we have to load the unit multiple times, producing multiple values, each of which can be used (exactly once) by the dependents.
In later posts we’ll see some common patterns that let a unit “share state” across all of its uses. As you might guess, that requires taking advantages of some primitives provided by the host, since basic linear Swanson values don’t give you this ability.