Rasmus Andersson

Introduction to WebAssembly

2017-01-16T00:00:00+00:00

WebAssembly, or WASM for short, is a new technology for running portable programs in a safe and efficient manner primarily aimed at the web platform. Similarly to ASM.js, WASM aims at a low level-of abstraction suitable as an intermediate representation of a higher-level program — i.e. WebAssembly code is intended to be generated by compilers rather than being written by humans. The W3C community group includes representatives from the largest web-browser companies, including Google, Microsoft, Apple and Mozilla making this whole thing rather exciting.

If you’re reading this chances are you’re already familiar with WASM to some extent. If you aren’t, this would be a good time to check out webassembly.org. At the time of publishing this article, WebAssembly has just reached the Browser Preview milestone, meaning that version 1 of WebAssembly will very likely be what the current draft describes. The specifics of this article are for version mvp-13.

There are some existing compilers which are getting “WASM’d”, but this article is going to focus on creating WASM programs without lots of dependencies or high-level languages.

Let’s get started.

Anatomy of a WebAssembly program

Actually, it’s called a “module” since with WebAssembly there’s no difference between a “program” and a “library” — there are only “modules”, each which can tie in and communicate with other modules, and each which can have a “main” function.

First off a module expresses which version of WebAssembly it uses for its encoding. What then follows are a variable number of sections, each containing information about the module. A module always begins with standard sections where order is important, and optionally ending in any number of custom sections that can contain any kind of data, all ignored by standard WASM virtual machines.

The standard sections in WASM version 1 are as follows, where sections required for any functional module is marked by an asterisk (*):

Type* — Function signature declarations
Import — Import declarations
Function* — Function declarations
Table — Indirect function table and other tables
Memory — Memory attributes
Global — Global declarations
Export — Exports
Start — Start function declaration
Element — Elements section
Code* — Function bodies
Data — Data segments

The type section contains a list of each unique function signature used throughout the module. This includes any signatures of imported functions. The position in the list is the type signature’s unique index within the module. E.g.

(i32 i32 -> i32)  // func_type #0
(i64 -> i64)      // func_type #1
( -> )            // func_type #2

WebAssembly has only four concrete types: 32-bit integer, 64-bit integer, 32-bit floating-point number and 64-bit floating-point number where the integer types are sign-agnostic (more on this later) and floating-point numbers following the IEEE 754-2008 standard. Any complex types can be built on top of these basic types by a compiler. The rest of this article, as well as the WebAssembly documentation, will refer to these basic types with the short names i32, i64, f32, and f64 respectively.

The import section declares any external dependencies by listing module name, field name and type for each function, value or data required:

("dumb-math", "quadruple", (func_type 1))        // func #0
("dumb-math", "pi", (global_type i64 immutable))

It’s up to the host system (e.g. web browser) to resolve these imports and this is how runtime-dynamic linking is made possible in WASM, and is also the foreign-function interface for interacting with non-WASM functions, as we will see later.

The function section declares indexes for each function that is later defined in the code section, where the position in the list is the function’s index and the value its type. The effective function index starts at number of func_type imports, meaning that the effective list of functions available in the module is the import section list filtered on function imports joined by the function-section list.

(func_type 1)  // func #1
(func_type 1)  // func #2
(func_type 0)  // func #3

When we later call functions, we will refer to them by their index (“func #N” above, where N is the function’s index.)

The table section defines any number of tables. Tables are mechanisms for mapping opaque values which can not be represented in nor directly accessed by WebAssembly, like for instance a JavaScript object or an operating-system file handle. This feature bridges the gap between low-level, untrusted linear memory and high-level opaque handles/references at the cost of a bounds-checked table indirection. We won’t go into more detail about tables.

The memory section defines the optional memory of the module by defining its initial size and optionally how large it is expected to expand. The data section can be used to initialize the memory.

The global section declares any number of mutable or immutable global variables for the module. These are equivalent to static variables in C and C++.

The export section declares any parts of the module that can be accessed by the host environment, not including the special start function, which we will get to in a just a few sentences.

("half" (func 1))

The above would export function 1 as “half”. If we look at the function section above, we can see that func #1’s type is func_type #1, so the host environment will see this as:

function half(arg0 :int64) :int64

In addition to functions, modules can also export tables, memory segments and global variables to the outside world.

The start section designates a function index for a function to be called when the module is loading and is the mechanism that can be used to make a module an executable program, or used to dynamically initialize globals or memory of a module.

The element section allows a module to initialize the contents of a table imported from the outside or defined in the table section.

The code section is probably the bulk of most WebAssembly modules as it defines all code for all functions in the module. The function bodies are defined in the same order as their respective function indexes in the function section, not including imports of course. Our “half” function’s body could be defined like this:

get_local 0  // push parameter #0 on stack (our dividend)
i64.const 2  // push constant int64 "2" on stack (our divisor)
i64.div_u    // unsigned division; pushes result onto stack
end          // ends function, resulting in one i64 (top of stack)

You probably already guessed it: WebAssembly is a stack machine which means that we push and pop values onto and off from a virtual stack. Most WASM operator codes (“opcode” for short) takes and/or adds a well-defined amount of values to the stack.

Let’s walk through to see what happens to the stack if we run the code of our “half” function:

A few things to note about this diagram:

The stack is abstract in the sense that we can’t index into it, measure it or inspect it; we can only push to and pop from it. This leaves the door open to efficient VM implementations.
The 4th step above is probably never an actual state in a real VM as there would be no reason to actually empty the stack; the step illustrates what is theoretically happening to the stack.
At the end the function implicitly returns and the caller will have one value (the result) available on the stack.

There are quite a lot of number operators defined by WASM 1 — too many to list here. However, you might find it comforting knowing that in addition to all basic operations you’d expect, like div and add, there are several other useful common numeric operations defined as opcodes rather than being left to be implemented on top of other, simpler instructions. For example:

eqz efficiently tests if an integer operand is zero, minimizing stack thrash from otherwise pushing the constant 0 and calling eq.
popcnt counts the number of bits set in an integer
ceil and floor performs the ceiling and floor functions on a floating-point number
sqrt calculates the square root of a floating-point number

There is also a versatile repertoire of conversion operators as well, for converting between any two types with well-defined behavior.

Last but not least is the data section which can be used to initialize imported or local memory:

(data_segment
  0                          // linear memory index
  (init_expr (i32.const 4))  // byte offset at which to place the data
  (data 0x2a 0x0 0x0 0x0))

This would initialize bytes [4–8] in the 0th memory with the provided byte values, which if read as an unsigned i32 yields the number “42”.

Managing data and values

We’ve looked at the WebAssembly value stack for saving and reading basic values. There are a few more ways to manage data and state in your modules.

Stack: Machine operations takes their operands from—and put their result onto—the stack.
Locals and globals are like variables: named and can hold any of the same basic types as the stack can hold (i32, et al.)
Memory: Random-accessible array of bytes where we can store anything we want.
Elements: “Handles” for opaque foreign values (like OS file handles.)

Locals are like variables in many higher-level programming languages: we can name them, store values to them and load values from them. Locals are named using function-local integer index.

When defining a function body, we can declare any number of locals for the function’s code. Parameters to a function are also locals and the “name” index of locals start at 0 with the first function parameter and continue incrementing with each additional parameter and eventually with each listed local of the function body. Locals are always initialized to zero (all their bits are 0.)

In our example earlier in this article we used the operation get_local to push the value of the 1st function parameter onto the stack. We can also perform the reverse: popping a value off of the stack and storing it into a local.

i32.const 123  // for the purpose of demonstration, push "123" to the stack
set_local 0    // pop "123" off of the stack and store it into local #0
// use the stack for other operations...
get_local 0    // "123" is pushed to the top of the stack

Locals makes it possible to hold on to temporary values while performing other operations that would otherwise replace or move a value off the stack.

Globals are a form of module-wide locals with their own indexes and operators, but otherwise shares the semantics of locals. The global index starts with any imported globals and continues incrementing with any globals defined in the global section. We can load and store global values using the get_global and set_global operations.

Memory is the most flexible as it allows us to store any data we can imagine, but trades ease-of use for flexibility:

Memory is linear
Size of a memory is an even multiple of the memory-page size, which is 64 KiB
Memory can be either imported or declared by the module.

Memory being “linear” means that there’s no random allocator operators available — all memory addresses used in a module’s code are expressed in terms of byte offsets from the beginning of a memory segment. WASM being a low-level format, this makes a lot of sense. It’s up to the higher-level language that targets WASM to provide memory management on top of this linear memory space, if needed.

Elements are opaque “value handles” that mean something to the host environment, but are opaque to WebAssembly. For example an element might represent an operating-system file handle or a JavaScript object if the host environment runs JavaScript.

Elements are cool, but memory is a lot more interesting, so let’s get back to learning about memory and what it enables us to do.

Future versions of WASM might allow multiple memory segments to be used, but version 1 only uses a single segment per module, which simplifies a lot of things, like memory operators:

i32.load alignment offset loads a 32-bit integer from the byte range [start..start+4), where start is an integer operand popped from the stack
i64.store16 alignment offset stores a 16 bit integer, by wrapping a 64-bit integer popped off of the stack, to the byte range [start-start+2), where start is an integer operand which is also popped from the stack.

The following code stores an i32 “123” at byte range [4..7]:

i32.const 4    // byte-sized address
i32.const 123  // value to store
i32.store 2 0  // 2 = 32-bit/4-byte alignment, 0 = offset

We can load the value back onto the stack at a later time:

i32.const 4
i32.load 2 0   // after this, the top of the stack is i32 "123"

The flexibility of memory is not only in the fact that we can load things that were stored in the past—we can do that with locals too—but that memory is persistent for the duration of a module’s lifetime, meaning we can access values across functions, interpret the same data as different types, and store byte-sized values in a much more compact manner than locals, globals and the stack uses.

Imagine that we want to call a function with the name of our favorite buddy, “Lolcat”. Encoding the name as UTF-8 text, each character only needs 1 byte (so 6 bytes in total plus some additional sentinel or length value). A naïve and very inflexible way of doing this would be to push each character onto the stack and have the callee accept some predetermined number of parameters, e.g. function (c0, c1, c2, c3, c4, c5 i32) :void:

i32.const 0x4c // 'L'
i32.const 0x6f // 'o'
i32.const 0x6c // 'l'
i32.const 0x63 // 'c'
i32.const 0x61 // 'a'
i32.const 0x74 // 't'
call 1         // call a function that takes exactly 6 parameters

Not only is this ridiculously inflexible, but it requires a lot of stack space — each “card on the stack” is one machine word large. On a 32-bit system (or 32-bit virtual machine), that means each letter of our “Lolcat” string occupies 4 bytes, bringing the total to 24 bytes. Another thing to consider is that the stack, although abstract, has a limit; if we push too many values to the stack without popping some off, the host machine will panic and crash our module.

This is a task for memory. Instead let’s imagine the callee function to take just a single argument that is the memory address of the string, e.g. function (addr i32) :void. First, when we assemble out module we initialize a part of module’s memory with the “Lolcat” string:

(data_segment 0
  (init_expr (i32.const 4))  // byte offset at which to place the data
  (data 0x4c 0x6f 0x6c 0x63 0x61 0x74 0x0))

Notice how in this example we place an additional “sentinel” zero byte at the end of the string. This is common in languages like C but generally discouraged. If you’re writing a real program you probably want to prefix the string with its length instead, but the “sentinel byte” will do for our example.

We can now call the function with the address (4) of the string:

i32.const 4  // byte offset into memory, "passed" as an argument to...
call 1       // call the receiving function

The receiving function would then load whatever parts of the string it needs from memory. For instance, say that it calls an imported “putc” function (which puts a byte to the programs stdout stream):

void print_str(i32 addr) {
  i32 byte = 0;
  while (true) {
    byte = i32.load8_u(addr);
    if (byte == 0) { break; }
    putc(byte);
    addr = addr + 1;
    continue;
  }
}

In WASM we have declared the need for one additional local (local #1; the byte variable) in our function and can now implement the equivalent functionality:

block void          // declares a "label" at it's "end"
  loop void         // declares a "label" right here
    // byte = i32.load8_u(addr)
    get_local 0     // push addr
    i32.load8_u 0 0 // push the byte at addr as an i32
    tee_local 1     // store the byte to local 1, but don't pop it

    // if (byte == 0) { break }
    i32.eqz         // (x i32) => i32(x == 0 ? 1 : 0)
    br_if 1         // if the byte was zero, jump to end of "block"

    // putc(byte)
    get_local 1     // push byte
    call 0          // call imported "putc" function with the byte

    // addr = addr + 1
    get_local 0     // push addr
    i32.const 1     // push i32 "1"
    i32.add         // push result from addr + 1
    set_local 0     // store new address to "addr" local

    // continue
    br 0            // jump to "loop" (i.e. continue looping)
  end
end // end of "block"

Addressing memory

You may have noticed that we provide two immediate values to the load and store operators. The first immediate value is an alignment “hint” that is a power-of 2 encoded as log2(alignment). In practice this means that the alignment immediate is one of the following values: 0 = 8-bit, 1 = 16-bit, 2 = 32-bit, and 3 = 64-bit.

If the effective address of a memory access is a multiple of the alignment attribute value of the memory access, the memory access is considered aligned, otherwise it is considered misaligned. Aligned and misaligned accesses have the same behavior.¹

The alignment hint is like a promise to the virtual machine executing our code that “the effective address is going to be aligned at N bits”, information which the VM will use to optimize our code. When we promise a certain alignment but fail to keep that promise by providing an address that is misaligned, the operation will likely be much slower than if we had provided an aligned effective address.

Therefore as a rule of thumb, you should only promise what you can keep — hint at the largest possible alignment for any operation, but no larger than the native alignment (32-bit for wasm32, 64-bit for wasm64.)

The second immediate for load and store operators is the address offset. This has proven to be a point of confusion already, so let’s clarify what the offset really is, what the effective address is and what happens to memory as we store and load values.

Here’s an illustration of the beginning of linear memory, initialized to zero:

The effective address is the offset in bytes measured from the beginning of the memory. The effective address is the sum of the address operand and the offset immediate.

effective-address = address-operand + offset-immediate

You might ask “why would I ever need offset if I have an address operand”? And it’s a fair question; as we’ve seen in previous examples, we can provide a constant value (e.g. using i32.const) for the address operand. However when we start using dynamic addresses, like we did in our “print_str” function earlier, it can be very useful for a compiler to add a constant offset to all memory operations of a module’s functions in order to “relocate” one area of memory to another.

WASM provides a rich set of memory operators for each of the four basic types, allowing reading some number of bytes as some kind of number. For instance, we can store a 64-bit integer in two bytes by truncating the value to a 16-bit integer:

i32.const 3      // address-operand = 3
i64.const 1234   // value
i64.store16 1 3  // alignment = 1 = 16-bit, offset-immediate = 3
                 // effective-address = 3 + 3 = 6

Since we hint at a 16-bit alignment and the effective address is an even multiple of 2 (2 bytes = 16 bits), this is an optimized (aligned) store. Our memory now looks like this, with the segment stored to is marked with dark background color:

WebAssembly always uses little-endian encoding for values in memory, no matter what the host platform’s native “endianess” is. This means that the 16-bit integer “1234” is encoded as 0xd2 0x04.

If we had stored a 32-bit or 64-bit value instead, the store would have been misaligned and inefficient since effective-address “6” is in the middle of a 32-bit and 64-bit word:

i64.store32 2 3  // align = 2 = 32-bit, offset = 3  =>  addr = 6

The red arrows indicate that for the store to be aligned as promised (at 32-bit boundaries), we’d have to either decrease or increase our address by 2 (i.e. 6 ± 2).

A load or store is aligned when the effective address is at the boundary of the promised alignment magnitude.

Let’s adjust the offset-immediate to get a 32-bit aligned store:

i64.store32 2 5  // align = 2 = 32-bit, offset = 5  =>  addr = 8

Optimal, aligned store.

Converting between and reinterpreting values

We are free to interpret any bytes as any value. For instance we can load the four bytes representing a 16-bit integer that we stored above as a 32-bit floating-point number:

i32.const 4   // address-operand = 4
f32.load 2 4  // align = 2 = 32-bit, offset = 4  =>  addr = 8

The top of the stack now contains a f32 representing roughly the number “1.7292e-42”, which is possibly not what you would have expected. Remember, we didn’t convert a number from one type to another, we just interpreted the raw data used to represent one type as another type.

If our intention was to load the i32 value as an equivalent f32 number, we instead use one of the numeric conversion operators for the destination type:

i32.const 4       // address-operand = 4
i32.load 2 4      // align = 2 = 32-bit, offset = 4  =>  addr = 8
f32.convert_u_i32

The top of the stack is now an f32 with the value “1234.0”.

Floating-point numbers are always “signed”, but integers can be unsigned. “But… we’ve been working with i32’s all article long and I haven’t seen any sign-specific operators!?” Most of the operators we’ve been using so far only needs to know the size of the data, and doesn’t care if the value is meant to be interpreted as being signed or not. WebAssembly integer values are fundamentally sign-agnostic.

There are of course a few operations which requires knowing whether its operands are signed or unsigned. For instance, the “less than” operator needs to know if it’s comparing potentially negative numbers.

Operators that are sign-dependent has a _s or _u suffix. Here are a few:

i32.lt_s    //   signed-i32  <    signed-i32
i32.lt_u    // unsigned-i32  <  unsigned-i32
i32.div_s   //   signed-i32  /    signed-i32
...

JavaScript API

Note: The following section is out of date. Please refer to the official documention.

As “WebAssembly” hints with “Web” in its name, the first useful WebAssembly platforms are the cutting-edge versions of the most popular web browsers: Chrome, Firefox, Safari and Edge. At the time of writing this article, WebAssembly needs to be enabled through the browser’s advanced settings. In Chrome the setting is found under “flags” (chrome://flags/#enable-webassembly).

I’m not going to talk much about this since there’s plenty of good information on the JavaScript browser API. Here’s an example of loading a module, “instantiating” it (running it) and finally calling one of its exported functions from JavaScript:

WebAssembly.compile(new Uint8Array(
  `00 61 73 6d  0d 00 00 00  01 09 02 60  00 00 60 01
7f 01 7f 03  03 02 00 01  05 04 01 00  80 01 07 07
01 03 66 6f  6f 00 01 08  01 00 0a 3a  02 02 00 0b
35 01 01 7f  20 00 41 04  6c 21 01 03  40 01 01 01
0b 03 7f 41  01 0b 20 01  41 e4 00 6c  41 cd 02 20
01 1b 21 01  41 00 20 01  36 02 00 41  00 21 01 41
00 28 02 00  0f 0b 0b 0e  01 00 41 00  0b 08 00 00
00 00 2c 00  00 00`.split(/[\s\r\n]+/g).map(v => parseInt(v, 16))
)).then(mod => {
  let m = new WebAssembly.Instance(mod)
  console.log('foo(1) =>', m.exports.foo(1))
  console.log('foo(2) =>', m.exports.foo(2))
  console.log('foo(3) =>', m.exports.foo(3))
})

If we paste this into a WebAssembly-enabled browser’s console, we should see the result of some simple computations done by the module:

foo(1) => 400
foo(2) => 800
foo(3) => 1200

This hopefully gives you a hint of how WASM can inter-operate with JavaScript to actually be practical and useful as an incremental step toward a WebAssembly-powered app. Perhaps you’ll write your UI in React & JavaScript, but write something like a JPEG encoder or file-format parser in WASM, having it all play nicely together.

wasm-util

I’ve put together a small collection of TypeScript/JavaScript code for working with WASM dubbed wasm-util. This code has no dependencies and is structured in a way that makes it possible to use only a few select source files for tasks that only require some functionality.

ast provides a full TypeScript type system for the complete WebAssembly specification and constructors for all parts of a WebAssembly module.
emit provides helpers for emitting WASM byte code from an AST.
repr generates a human-readable text representation of an AST.
lbtext generates Linear Bytecode text from AST instructions.

See wasm-util readme for a complete listing of functionality.

I found myself relying on a very complicated tool chain (source build of llvm, binaryen, etc) while all I was looking for was to get close to WebAssembly. The prime component of wasm-util is ast which provides a convenient way of building complete WASM modules, with full static type-checking if you’re using TypeScript.

Following is an example of building a module that provides the factorial function. Let’s start by describing the function we’re making in a C-like syntax:

int64 factorial(int64 n) {
  return (n == 0) ? 1
                  : n * factorial(n-1);
}

The equivalent WebAssembly code looks like this:

get_local 0    // push parameter #0 on stack.
i64.const 0    // push constant int64 "0" on stack.
i64.eq         // execute "eq" which pops two operands from stack
               //  and pushes int32 "1" or "0" on stack.
if i64         // pops one int32 from stack; if its not "0":
  i64.const 1  //   push constant int64 "1" on stack.
else           // else (if operand was "0"):
  get_local 0  //   push parameter #0 on stack. [1]
  get_local 0  //   push parameter #0 on stack.
  i64.const 1  //   push constant int64 "1" on stack.
  i64.sub      //   execute "sub[tract]" which pops two operands
               //    from stack (parameter #0 and constant "1")
               //    and finally pushes the result int64 on stack.
  call 0       //   call function #0 ("factorial") which pops one
               //    int64 from the stack and when it returns an
               //    int64 has been pushed on stack
  i64.mul      //   execute "sub[tract]" which pops two operands
               //    from stack ([1] and result from function call)
               //    and finally pushes the resulting int64 on stack
end            // ends function, returning one int64 result (on stack.)
               // Stack now contains one int64 value that's the result from one of
               // the two branches above.

The above code was printed by lbtext, for which we provided an AST built with the ast module:

import ... 'wasm-util/ast'
const mod = c.module([

  type_section([
    func_type([i64], i64), // type index = 0
  ]),

  function_section([
    varuint32(0), // function index = 0, using type index 0
  ]),

  export_section([
    // exports "factorial" as function at index 0
    export_entry(
      str_ascii("factorial"),
      external_kind.function,
      varuint32(0)),
  ]),

  code_section([
    // body of function at index 0:
    function_body([ /* additional local variables here */ ], [
      if_(i64, // i64 = result type of `if` expression
        i64.eq(get_local(i64, 0), i64.const(0)), // condition
        [ // then
          i64.const(1)
        ], [ // else
          i64.mul(
            get_local(i64, 0),
            call(i64, varuint32(0), [ // 0 = function index
              i64.sub(get_local(i64, 0), i64.const(1))
            ]))])])]
  )]
)

We can now generate WASM bytecode through the Emittable interface:

const emitbuf = new BufferedEmitter(new ArrayBuffer(mod.z))
mod.emit(emitbuf)
// the array buffer (emitbuf.buffer) now contains the complete module code

Or print a human-readable representation of the AST:

import { strRepr } from 'wasm-util/repr'
console.log(strRepr(mod))

Which yields the following in the console:

(module 13
  (section type 6 1
    (func_type (i64) i64))
  (section function 2 1 0)
  (section export 13 1
    (export_entry "factorial" external_kind.function 0))
  (section code 25 1
    (function_body 23 0
      (if [i64]
        (i64.eq
          (get_local [0])
          (i64.const [0])
        )
        (then
          (i64.const [1]))
        (else
          (i64.mul
            (get_local [0])
            (call [0]
              (i64.sub
                (get_local [0])
                (i64.const [1])
              )))) end) end)))

A complete version of this “factorial” demo can be found as a unit test in the wasm-util repository.

With wasm-util you can get started playing around with building your own WebAssembly programs right now with a minimum amount of effort. Perhaps you’re the author of a compiled language and are interested in targeting WASM — this might be a good way to get started.

———

If it’s not already clear from this article: I believe in a bright future for WebAssembly. The web is an amazing concept that is currently falling short carrying a heavy legacy from the past. In order to bring truly great experiences to the web and blur the lines of what is and what isn’t a “native” experience, WebAssembly—or something else like it—needs to happen.

At Figma we’re building one of the most complex and performance-critical apps there is on the web platform today, and we are very excited to start moving from ASM.js to WebAssembly. Does this stuff excite you? We’re hiring :)

WASM as Intermediate Representation

As I was writing this article it slowly dawned on me that WebAssembly might be an excellent IR (Intermediate Representation) for compilers of all sorts.

An intermediate representation is a representation of a program part way between the source and target languages. A good IR is one that is fairly independent of the source and target languages, so that it maximizes its ability to be used in a retargetable compiler.²

WebAssembly really has no dependencies on anything “web” and its module and bytecode format is at such a low level that it can be used to represent any other higher-level program.
There are several high-quality VMs being implemented, many of them in web browser, which can execute WASM programs efficiently, making distribution a bliss (the web!)
WASM code can be translated to machine code.
WASM can be interpreted and emulated which makes debugging a whole lot more pleasant than debugging programs which only run natively. How about we stop the world and interactively inspect the stack? How about we play back an interpreted recording that reproduces a bug deterministically?

Want to help out? Join the community and come hang in #webassembly on irc.w3c.org

Gotalk

2015-01-21T00:00:00+00:00

Gotalk exists to make it easy for programs to talk with one another over the internet, like a web app coordinating with a web server, or a bunch of programs dividing work amongst eachother.

Gotalk takes the natural approach of bidirectional and concurrent communication — any peer have the ability to expose “operations” as well as asking other peers to perform operations. The traditional restrictions of who can request and who can respond usually associated with a client-server model is nowhere to be found in gotalk.

Gotalk in a nutshell

Bidirectional

There’s no discrimination on capabilities depending on who connected or who accepted. Both “servers” and “clients” can expose operations as well as send requests to the other side.

Concurrent

Requests, results, and notifications all share a single connection without blocking eachother by means of pipelining. There’s no serialization on request-result or even for a single large message, as the gotalk protocol is frame-based and multiplexes messages over a single connection. This means you can perform several requests at once without having to think about queueing or blocking.

Simple

Gotalk has a simple and opinionated API with very few components. You expose an operation via “handle” and send requests via “request”.

Handle("greet", func(params In) (Out, error) { ... })
// ...
Request("greet", params, &result)

Practical

Gotalk includes a JavaScript implementation for Web Sockets alongside the full-featured Go implementation, making it easy to build modern web applications. The Gotalk source code also includes a number of easily-readable examples.

handle("greet", function (params, result) { ... });
// ...
request("greet", params, function (err, result) { ... });

Debuggable

The Gotalk protocol’s wire format is byte based for easy on-the-wire inspection of data. It can thus be operated over any reliable byte transport. For example, here’s a protocol message representing a request for an operation “hello” with the parameter “world”:

r001005hello00000005world

By example

As just mentioned earlier, there are a few examples in the examples directory demonstrating how you can use Gotalk. But let’s explore a simple program right here — a little something written in Go which demonstrates the use of an operation named “greet”:

func server() {
  gotalk.Handle("greet", func(in GreetIn) (GreetOut, error) {
    return GreetOut{"Hello " + in.Name}, nil
  })
  if err := gotalk.Serve("tcp", "localhost:1234"); err != nil {
    log.Fatalln(err)
  }
}

func client() {
  s, err := gotalk.Connect("tcp", "localhost:1234")
  if err != nil {
    log.Fatalln(err)
  }
  greeting := &GreetOut{}
  if err := s.Request("greet", GreetIn{"Rasmus"}, greeting); err != nil {
    log.Fatalln(err)
  }
  log.Printf("greeting: %+v\n", greeting)
  s.Close()
}

Let’s look at the above example in more detail, broken apart to see what’s going on.

We begin by importing the gotalk library together with log which we use for printing to the console:

package main
import (
  "log"
  "github.com/rsms/gotalk"
)

We define two types: Expected input (request parameters) and output (result) for our “greet” operation:

type GreetIn struct {
  Name string `json:"name"`
}
type GreetOut struct {
  Greeting string `json:"greeting"`
}

Registers a process-global request handler for an operation called “greet” accepting parameters of type GreetIn, returning results of type GreetOut:

func server() {
  gotalk.Handle("greet", func(in GreetIn) (GreetOut, error) {
    return GreetOut{"Hello " + in.Name}, nil
  })

Finally at the bottom of our server function we call gotalk.Serve, which starts a local TCP server on port 1234:

  if err := gotalk.Serve("tcp", "localhost:1234"); err != nil {
    log.Fatalln(err)
  }
}

In our client function we start by connecting to the server:

func client() {
  s, err := gotalk.Connect("tcp", "localhost:1234")
  if err != nil {
    log.Fatalln(err)
  }

Finally we send a request for “greet” and print the result:

  greeting := GreetOut{}
  if err := s.Request("greet", GreetIn{"Rasmus"}, &greeting); err != nil {
    log.Fatalln(err)
  }
  log.Printf("greeting: %+v\n", greeting)

  s.Close()
}

Output:

greeting: {Greeting:Hello Rasmus}

Gotalk in the web browser

Gotalk is implemented not only in the full-fledged Go package, but also in a JavaScript library. This allows writing web apps talking Gotalk via Web Sockets possible.

// server.go:
package main
import (
  "net/http"
  "github.com/rsms/gotalk"
)
func main() {
  gotalk.HandleBufferRequest("echo", func(in []byte) ([]byte, error) {
    return in, nil
  })
  http.Handle("/gotalk", gotalk.WebSocketHandler(nil, nil))
  http.Handle("/", http.FileServer(http.Dir(".")))
  err := http.ListenAndServe(":1234", nil)
  if err != nil {
    panic("ListenAndServe: " + err.Error())
  }
}

In our html document, we begin by registering any operations we can handle:

<!-- index.html -->
<body>
<script type="text/javascript" src="gotalk.js"></script>
<script>
gotalk.handle('greet', function (params, result) {
  result({ greeting: 'Hello ' + params.name });
});
</script>

We can’t “listen & accept” connections in a web browser, but we can “connect” so we do just that, connecting to “/gotalk” which is where we registered gotalk.WebSocketHandler in our server.

<!-- index.html -->
<body>
<script type="text/javascript" src="gotalk.js"></script>
<script>
gotalk.handle('greet', function (params, result) {
  result({ greeting: 'Hello ' + params.name });
});

gotalk.connect('ws://'+document.location.host+'/gotalk', function (err, s) {
  if (err) return console.error(err);
  // s is a gotalk.Sock
});
</script>

This is enough for enabling the server to do things in the browser …

But you probably want to have the browser send requests to the server, so let’s send a “echo” request just as our connection opens:

gotalk.connect('ws://'+document.location.host+'/gotalk', function (err, s) {
  if (err) return console.error(err);
  s.request("echo", "Hello world", function (err, result) {
    if (err) return console.error('echo failed:', err);
    console.log('echo result:', result);
  });
});

We could rewrite our code like this to allow some UI component to send a request:

var s = gotalk.connect('ws://'+document.location.host+'/gotalk', function (err, s) {
  if (err) return console.error(err);
});

button.addEventListener('click', function () {
  s.request("echo", "Hello world", function (err, result) {
    if (err) return console.error('echo failed:', err);
    console.log('echo result:', result);
  });
});

The request will fail with an error “socket is closed” if the user clicks our button while the connection isn’t open.

If you’re interested in learning more about using Gotalk with web browsers, check out examples/websocket and examples/websocket-chat which shows how to use most of the Gotalk functionality to make interactive websites.

Protocol and wire format

The wire format is designed to be human-readable and flexible; it’s byte-based and can be efficiently implemented in a number of environments ranging from HTTP and WebSocket in a web browser to raw TCP in Go or C. The protocol provides only a small set of operations on which more elaborate operations can be modeled by the user.

Here’s a complete description of the protocol:

conversation    = ProtocolVersion Message*
message         = SingleRequest | StreamRequest
                | SingleResult | StreamResult
                | ErrorResult

ProtocolVersion = <hexdigit> <hexdigit>

SingleRequest   = "r" requestID operation payload
StreamRequest   = "s" requestID operation payload StreamReqPart+
StreamReqPart   = "p" requestID payload
SingleResult    = "R" requestID payload
StreamResult    = "S" requestID payload StreamResult*
ErrorResult     = "E" requestID payload
Notification    = "n" type payload

requestID       = <byte> <byte> <byte>

operation       = text3
type            = text3

text3           = text3Size text3Value
text3Size       = hexUInt3
text3Value      = <<byte>{text3Size} as utf8 text>

payload         = payloadSize payloadData?
payloadSize     = hexUInt8
payloadData     = <byte>{payloadSize}

hexUInt3        = <hexdigit> <hexdigit> <hexdigit>
hexUInt8        = <hexdigit> <hexdigit> <hexdigit> <hexdigit>
                  <hexdigit> <hexdigit> <hexdigit> <hexdigit>

A conversation begins with the protocol version:

00  -- ProtocolVersion 0

If the version of the protocol spoken by the other end is not supported by the reader, the connection is terminated and the conversation never starts. Otherwise, any messages are read and/or written.

This is a “single-payload” request …

+----------------- SingleRequest
|  +---------------- requestID   "001"
|  |  +------------- text3Size   4
|  |  |   +--------- operation   "echo"
|  |  |   |       +- payloadSize 25
|  |  |   |       |
r001004echo00000019{"message":"Hello World"}

… and a corresponding “single-payload” result:

+----------------- SingleResult
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 25
|  |       |
R00100000019{"message":"Hello World"}

Each request is identified by exactly three bytes—the requestID—which is requestor-specific and has no purpose beyond identity, meaning the value is never interpreted.

These “single” requests & results are the most common protocol messages, and as their names indicates, their payloads follow immediately after the header. For large payloads this can become an issue when dealing with many concurrent requests over a single connection, for which there’s a more complicated “streaming” request & result type which we will explore later on.

If an error occurs while handing a request, an “error” is send as the reply instead of a regular result:

+----------------- ErrorResult
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 38
|  |       |
E00100000026{"error":"Unknown operation \"echo\""}

As with all messages, what the payload data represents is up to each application and not part of the Gotalk protocol although we use JSON in our examples here.

When there’s no expectation on a response, Gotalk provides a “notification” message type:

+---------------------- Notification
|              +--------- type        "chat message"
|              |       +- payloadSize 50
|              |       |
n00cchat message00000032{"message":"Hi","from":"nthn","chat_room":"gonuts"}

Notifications are never replied to nor can they cause “error” results.

For more complicated scenarios there are “streaming-payload” requests and results at our disposal. This allows transmitting of large amounts of data without the need for large buffers. For example this could be used to forward audio data to audio playback hardware, or to transmit a large file off of slow media like a tape drive or hard-disk drive.

Because transmitting a streaming request or result does not occupy “the line” (single-payloads are transmitted serially), they can also be useful when there are many concurrent requests happening over a single connection.

Here’s an example of a “streaming-payload” request …

+----------------- StreamRequest
|  +---------------- requestID   "001"
|  |      +--------- operation   "echo"
|  |      |       +- payloadSize 25
|  |      |       |
s001004echo0000000b{"message":

+----------------- streamReqPart
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 25
|  |       |
p0010000000e"Hello World"}

+----------------- streamReqPart
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 0 (end of stream)
|  |       |
p00100000000

… followed by a “streaming-payload” result:

+----------------- StreamResult (1st part)
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 25
|  |       |
S0010000000b{"message":

+----------------- StreamResult (2nd part)
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 25
|  |       |
S0010000000e"Hello World"}

+----------------- StreamResult
|  +---------------- requestID   "001"
|  |       +-------- payloadSize 0 (end of stream)
|  |       |
S00100000000

Requests and results does not need to match on the “single” vs “streaming” detail — it’s perfectly fine to send a streaming request and read a single response, or send a single response just to receive a streaming result. The payload type is orthogonal to the message type, with the exception of an error response which is always a “single-payload” message, carrying any information about the error in its payload. Note however that the current version of the Go package does not provide a high-level API for mixed-kind request-response handling.

Open source code

Gotalk is a hobby project and free to use, modify and even sell within the bounds of the liberal MIT-license. You’ll find the most recent version at https://github.com/rsms/gotalk

DBX 2013

2013-07-09T00:00:00+00:00

Dropbox’s first developer conference DBX was a lot of fun. Me and Adam Polselli gave a talk on “Designing Products for People” as seen in the video below.

Hello, Dropbox

2013-03-21T00:00:00+00:00

I’m very excited to let you know that I’m joining Dropbox.

After two years at Facebook I couldn’t be more proud. Proud to have been part of something as important as Facebook and proud of the work I’ve done with shaping the future of mobile communication. It’s truly been a fantastic time of my life — an experience rich of great people, mind-boggling challenges and once-in-a-lifetime experiences.

Look at the past for inspiration, but focus on the future, because tomorrow is shaped by the choices we make today.

At Dropbox I’m going to work hard to make all our lives better. Remove friction from technical details in our modern daily lives, and relieve us from worrying about our “stuff” — from quick snapshots and hasty notes to precious memories.

This is going to be such a fun adventure.

The 1950s called and wanted their toolbox back

2013-01-01T00:00:00+00:00

Your favourite fancy-pants modern programming language is from the 1950s.

Pretty much any programming language used today is a derivative of Fortran or Lisp, both born in the 1950s. Okay, reality check: It’s 2013—yes, 60 years later—and we have cars that drive themselves on the street, robots roaming the surface of alien planets and tiny networked devices with interactive surfaces that we keep in our pockets, which are orders of magnitude more powerful than the computers of the 1950s.

This might come as a surprise to readers not into computer programming, but professional and hobbyist programmers alike all use the same tools as we did 60 years ago — one-dimensional, sequential plain text. It’s like writing a single document in Word without using any formatting, with the goal of instructing a large symphony orchestra to perform a complex musical piece. That app you’re using could as well have been built in the 1950s, had we the same powerful hardware back then. We are thoughtlessly using Grandpa’s old toolbox to build a spaceship.

The Wikipedia article on computer programming opens up with the following description:

Computer programming […] is the process of designing, writing, testing, debugging, and maintaining the source code of computer programs.

Interestingly “writing” is an inherent part of this canonical description of “computer programming” — a subject under constant scrutiny. Programming has become synonymous with “writing code”, which really tickles my LOL, so to speak.

Jumping higher & beyond the written text

Writing is a universal tool we created for conveying information in a way that can be easily copied, shared and distributed. Although writing as a form of communication goes as far back as 5200 years (clay tablets used in Mesopotamia around 3200 BCE), we would not reach an interesting level of literacy until the late 19th century when reading was no longer exclusive to monks, academics and the educated upper class, but became an extremely important tool of humanity, propelling us into the industrial age and beyond. As a species we are builders. In a way, we have taken control of our evolution not by changing our minds or physique, to become larger so we can build greater things, but by building a tower of knowledge that enables us to create small and large tools which in turn enables us to build houses taller than a hundred people and explore the surface of alien planets no human has ever set a foot on.

Just as the now mundane tools pen and paper have evolved from blood and cave walls into sharp stones and clay tablets—into ink and papyrus into pen and paper and lately into stylus and screen—the fundamental tools (i.e. computer programming) we use today to build tomorrow’s toolbox (i.e. software) have not evolved to make use of our current arsenal of technology. How will we build software 20 years from now? 200 years from now? Hopefully not limited by the same factors as we are today, namely expressing multi-dimensional and naturally concurrent systems in one-dimensional, sequential text.

We seem to have reached an upper level of utility with our current toolbox for programming computers, much like the athletic Olympic sport of High Jump, where the current record of 2.45m has remained for 20 years — here we have reached the limit of the tool box (the human body.) To allow High Jump to “progress” further, we would either need to change the definition and rules of the sport or allow modified human bodies (i.e. doping, cybernetics, etc) to participate.

Our current toolbox for software creation has an inherent limitation at its very foundation: low bandwidth. One-dimensional, sequential text utilises only our sense of sight, and is interpreted by a small section of our brains, forming a “bridge” or “proxy” for meaning and expression.

The high-level goal of computer programming is to enable the creation of highly customised tools: A video player app is a tool for playing specific kinds of moving pictures synchronised with audio. The game on your smartphone that you play on the bus is a tool for creating feelings of accomplishment. The system of a bank is a specialised tool that keeps track of who has what money.

What about tomorrow?

So how do we make full use of today’s technology to enable these very creative individuals known as computer programmers—or rather; software engineers—to jump even higher? I doubt a thousand year old one-dimensional tool like text is the answer, when we perform other tasks in life using tools which make better use of our senses — touch and hearing, and don’t forget the higher-level senses like image recognition and spatial ability. Our minds are truly powerful and very able.

So it all comes down to Human-Computer Interaction, the field of interaction between people and computers. Programming is, in fact, just an interface for humans to control computers.

A good example is the car. If you owned a car in the 1800s you would know how to maintain that car. You would know how the engine operated, and you would be able to diagnose and fix problems. Today you simply press a button to start or stop the car. Open up the engine compartment hood of a modern car and you will probably just see a large flat surface with a logotype on it — the heart of the car has become irrelevant knowledge for most car operators like yourself.

The car of the 1800s would not be a very useful tool in today’s measures as it would likely break down during short trips, would not go very fast and was expensive to produce and operate. The car of today is an extremely able tool which extends your ability of transportation both in terms of time (speed), comfort, distance and freight. We have refined our tools (hammers and screwdrivers replaced by robotic specialised factories and lasers) by applying the process of interface abstraction to in order to make the human able to do more using less cognitive effort. They year of 2012 even brought us street-legal cars which drives themselves — a step further in the progress of abstraction, enabling us not only to transport ourselves long distances in comfort, but also free up time for other tasks (i.e. while the car is driving.)

The field of programming need to see a renaissance in fundamental reinvention, just as it did in the 1950s when programming machines using levers and buttons was replaced by programming machines using textual sequences of computer commands.

Okay, maybe we’re not in the movie Minority Report just yet, but still, today’s multi-sensory input-output technology like high-density interactive touch screens which “touches back” and spatial 3D positional audio are all interesting technology that just now have become economically viable and high-fidelity enough to be forgotten — “forgotten” as in us no longer thinking about the technology itself, but to be able to intuitively focus on whatever is presented and conveyed.

Visions for the future, from the past

In the rather profound Design Principles Behind Smalltalk in which Daniel Ingalls of the Xerox PARC expresses the interesting ethos of enabling creative individuals to program computers, we can read the following:

[…] a vision that includes a creative individual and the best computing hardware available.

Ingalls builds further on this vision, writing:

If a system is to serve the creative spirit, it must be entirely comprehensible to a single individual.

The point here is that the human potential manifests itself in individuals. To realize this potential, we must provide a medium that can be mastered by a single individual. Any barrier that exists between the user and some part of the system will eventually be a barrier to creative expression.

Back in 1981 when the above document was published, human-computer hardware interfaces were far from as high fidelity as they are today. There were no low-latency touch screens you could hold in your hand and there were no graphics processors able to render complex movie scenes on-the fly. Keyboards were still the lowest friction and efficient way for a human to provide a computer with input. With today’s hi-fi user input hardware we should be able to further lower the friction—the “barrier”—between the human and the computer, and at the same time also increase the bandwidth of communication.

As early as 1963 was alternative human-computer interaction hardware with potentially lower level of friction and higher bandwidth explored. Most notably is Sketchpad, which used a stylus pen with an interactive screen, as likely being the most significant invention in the field of HCI.

Below here is a video of Alan Kay’s famous talk “Doing with Images Makes Symbols” from 1987 in which we see both Sketchpad and GrAIL (another early graphical programming environment from 1968) in action:

Sketchpad segment start at 04:00. GrAIL segment starts at at 24:10.

Not only was Sketchpad the first ever stylus input device, but also pioneered graphical windows and object-oriented programming. The computer it ran on was large enough to have it’s own roof and had a total memory of 460 kilobytes (a small photo from your smartphone is likely to be 2-4 times larger that the entire memory of this machine), and the processor could perform 400 000 instructions per second. Your average smartphone today can perform around 4 000 000 000 instructions per second (per core) — that means that what’s in your pocket today is not only extremely small in comparison to the giant computer Sketchpad was running on in 1963, but is also 10 000 times more powerful.

Now, remember the 1950s called and still haven’t got their programming toolbox back.

The Definition of Design

2012-12-01T00:00:00+00:00

Questions by Mme. L. Amic, Answers by Charles Eames.

What is your definition of “Design”, Monsieur Eames?
One could describe design as a plan for arranging elements to accomplish a particular purpose.

Is Design an expression of art?
I would rather say it’s an expression of purpose. It may, if it’s good enough, later be judged as art.

Is Design a craft for industrial purposes?
No, but design may be a solution to some industrial problems.

What is the boundaries of Design?
What are the boundaries of problems?

Is Design a discipline that concerns itself with only one part of the environment?
No.

Is it a method of general expression?
No, it is a method of action.

Is Design a creation of an individual?
No, because to be realistic one must always recognize the influence of those that have gone before.

Is Design a creation of a group?
Very often.

Is there a Design ethic?
There are always design constraints and these often imply an ethic.

Does Design imply the idea of products that are necessarily useful?
Yes, even though the use might be very suttle.

Is it able to cooperate in the creation of works reserved solely for pleasure?
Who would say that pleasure is not useful?

Ought form to derive from the analysis of function?
The great risk here is that the analysis may be incomplete.

Can the computer substitute for the Designer?
Probably, in some special cases but usually the computer is an aid to the designer.

Does Design imply industrial manufacture?
Not neccessarily.

Is Design used to modify an old object through new techniques?
This is one kind of design problem.

Is Design used to fit up an existing model so that it is more attractive?
One doesn’t usually think of design in this way.

Is Design an element of industrial policy?
If design constraints imply an ethic and if industrial policy includes ethical principles then yes, design is an element in industrial policy.

Does the creation of Design admit constraint?
Design depends largely on constraints.

What constraints?
The sum of all constraints. Here is one of the few effective keys to the design problem: the ability of the designer to recognize as many of the constraints as possible, his willingness and enthusiasm for working within these constraints. The constraints of price, size, strength, balance, time and so forth. Each problem has its own peculiar list.

Does Design obey laws?
Aren’t constraints enough?

Are there tendencies and schools in Design?
Yes, but these are more a measure of human limitation than of ideals.

Is Design ephemeral?
Some needs are ephemeral, most designs are ephemeral.

Ought Design to tend towards the ephemeral or towards permanence?
Those needs and designs that have a more universal quality tend toward relative permanence.

How would you define yourself with respect to a decorator? An interior architect? A stylist?
I wouldn’t.

To whom does Design address itself: to the greatest numbers? To the specialsts or the enlightened amateur? To a priviledged social class?
Design addresses itself to the need.

After having answered all these questions, do you feel you have been able to practice the profession of “Design” under satisfactory conditions, or even optimum conditions?
Yes.

Have you been forced to accept compromises?
I don’t remember ever being forced to accept compromises but I have willingly accepted constraints.

What do you feel is the primary condition for the practice of Design and for its propagation?
A recognition of need.

What is the future of Design?

…

Source: http://www.youtube.com/watch?v=3xYi2rd1QCg

Sol — a sunny little virtual machine

2012-10-14T00:00:00+00:00

During this weekend, together with a few evenings earlier this week, I created a rather simple virtual machine dubbed “Sol”, after the Swedish word for “sun”. I’ve read a lot about VM design and I’m into stuff like OS design, programming languages and other seeminlgy obscure and nerdy stuff surrounding the concept of a computer as a generic tool.

A virtual machine (VM) is a software implementation of a machine (i.e. a computer) that executes programs like a physical machine. — Wikipedia

Sol is a process virtual machine that runs inside an operating system process. However, inside Sol there are multiple tasks (just like most operating systems have processes) and so for a program running in Sol it does not matter what the world looks like on the outside. We could even make Sol boot directly from hardware, but that would just be crazytown. Trust me. I’ve been down that road before.

The purpose of Sol is learning. As we are defining our world, we have an extremely high degree of freedom. One major component of a virtual machine is the provided instruction set. An instruction is the simplest type of operation that a program can perform, and so the set of instructions provided by the virtual machine to programs running in it need to be universal and efficient.

Design overview

In the Sol VM there are one or more schedulers, each running on one CPU core (not yet implemented at the time of writing this).

Each scheduler maintains a list of tasks to be run. This list is called the run queue. A scheduler also maintains I/O watchers, timers, handles OS interrupts, etc. The scheduler does most of the work in Sol as it not only does all those fancy things I just described, but it also executes program code.

The run queue is a list of tasks ordered in the way they are scheduled.

The scheduler takes the first task in the list from the run queue
executes the task (more on what that means later).
If the task ended with an “end” or “error” status, the task is removed from the run queue…
…otherwise places the task at the end of the list.
If there are any I/O watchers or timers, check timers for expiry and possibly call the host OS kernel to check on pending “asynchronous” I/O events.
1. If an event has happened, like a timer expired or fired, the correlating task is added to the run queue so that the task can read the event it is waiting for.
The scheduler repeats this process (e.g. starting from point 1.) as long as there are any tasks in the run queue.

Let’s have a look at a task:

As we can see, a task is mostly an abstraction and contains only one significant component: Activation records. These comprise a task’s call stack and each activation record corresponds to one (active) function call. An activation record contains a reference to the function prototype (more on this in just a second) it’s executing, a program counter (usually called PC) which is a cursor for the currently executing program instruction and finally a registry for values.

A function prototype is the constants and the instruction of a function, but without a context (or “function closure”) with local variables etc. A function prototype is kind of like a building without any people or furniture. Albeit the name, it’s not really comparable to a blueprint as a function prototype is not copied or implemented, but is actually used as-is.

The program counter is simply a number that corresponds to an offset into the function prototype’s program (ordered list of instructions). As an activation record (we can think about this as a piece of running code) is executed, the program counter (PC) is incremented as each instruction is executed. Sometimes the PC is decremented, when a program jumps backwards (e.g. when performing a loop). The PC plays a central role in an instruction-based program (like your computer or phone’s hardware which is most likely incrementing a PC right now).

The registry is essentially a region of temporary memory that the executing program can use to store variable data. Imagine this simple function:

def foo(x, y):
  x = x * 5
  x = x * y
  return x

Here the program needs a way to store the value created by x * 5 that it can then pass to x * y which also needs to store its resulting value somewhere before using it with return. All local variables are stored in registers and thus access is very efficient. Something like this happens when executing the “foo” function (“R(x)” means “register x”):

argument 0 and 1 are already in R(0) and R(1)
load constant "5" into R(2)
multiply value-of R(0) with value-of R(2), put the result in R(0)
multiply value-of R(0) with value-of R(1), put the result in R(0)
return R(0)

Sol is a register-based virtual machine. Operands and results are read and stored from and to numbered registers, rather than “pushed” and “popped” to and from a stack (as with stack-based virtual machines). Register-based virtual machines avoid the push and pop operations usually surrounding other instructions, reducing code size, but in several cases also increases speed of execution (compared to stack-based virtual machines).

In the most excellent paper “The Implementation of Lua 5.0” Roberto, Luiz and Waldemar describes the (not really a) problem with code size and decoding overhead:

There are two problems usually associated with register-based machines: code size and decoding overhead. An instruction in a register machine needs to specify its operands, and so it is typically larger than a corresponding instruction in a stack machine. (For instance, the size of an instruction in Lua’s virtual machine is four bytes, while the size of an instruction in several typical stack machines, including the ones previously used by Lua, is one or two bytes.) On the other hand, register machines generate less opcodes than stack machines, so the total code size is not much larger.

Sol takes a lot of inspiration from Lua as well as Erlang.

Instructions and operations

An instruction consists of one or more components:

An operation code (e.g. “subtract a from b”)
0-3 operands (e.g. “register a and register b, results in register c”)

As a virtual machine has the disadvantage of being …virtual, we must do whatever we can in terms of assuring good performance, so one of these instructions fit into one machine word. Most hardware today is able to deal with 32-bit long chunks of data very efficiently, so inspired by Lua 5 I chose a 32-bit representation for Sol’s instructions.

Each instruction and its operands is encoded in one of three layouts (Behold, awesome ASCII art!.)

OP ABC — Operation OP with operands A, B and C:

0         5 | 6          13 | 14           22 | 23            31   Bit
------------|---------------|-----------------|-----------------
     OP     |       A       |        B        |        C           Field
------------|---------------|-----------------------------------
     6              8                9                 9           Bits
  [0..63]        [0..255]         [0..511]          [0..511]       Range

Some operations only need two operands and can be made more efficient if one of those operands is large enough for common values. For this need we define an alternate layout of an instruction:

OP ABx — Operation OP with operands A and Bs

Bu:

0         5 | 6          13 | 14                              31   Bit
------------|---------------|-----------------------------------
     OP     |       A       |              Bs/Bu                   Field
------------|---------------|-----------------------------------
     6              8                        18                    Bits
  [0..63]        [0..255]             Bu: [0..262143]              Range
                                      Bu: [-131071..131072]

A third class of operations only use one operand which size has a correlation with efficiency, so we define a third alternate layout of an instruction where the three operands are effectively collapsed into one 26-bit integer value:

OP Bxx — Operation OP with operand Bss

Buu:

0         5 | 6                                               31   Bit
------------|---------------------------------------------------
     OP     |                     Bss/Buu                          Field
------------|---------------------------------------------------
     6                               26                            Bits
  [0..63]                   Buu: [0..67108863]                     Range
                            Bss: [-33554431..33554432]

A, B, C, Bu and Buu signify unsigned integers whilst Bs and Bss signify signed integers. As we can read above, there’s room for 64 operations and 256 registers (OP=6 bits, A=8 bits) with this configuration. More than we need :)

Changing and maintaining instructions (operations + operands) is simple in Sol. I’ve intentionally gone to great lengths in order to make playing around with the instuction set easy. The file instr.h contains a list of instructions:

/* Control flow */ \
_(YIELD,      ABC) /* suspend and reschedule */\
_(JUMP,       Bss) /* PC += Bss */\
_(CALL,       ABC) /* R(A), ... ,R(A+C-1) := R(A)(R(A+1), ... ,R(A+B)) */\
_(RETURN,     AB_) /* return R(A), ... ,R(A+B-1) */\
/* Data */ \
_(LOADK,      ABu) /* R(A) = K(Bu) */\
_(MOVE,       AB_) /* R(A) = R(B) */\
_(DBGREG,     ABC) /* special: Debug dump register values */\
/* Arithmetic */ \
_(ADD,        ABC) /* R(A) = RK(B) + RK(C) */\
_(SUB,        ABC) /* R(A) = RK(B) - RK(C) */\
_(MUL,        ABC) /* R(A) = RK(B) * RK(C) */\
...

Sol’s source code is setup in such a way that changing this list is all that is required, apart from the actual implementation of each instruction. Adding or renaming an instruction automatically makes convenience symbols and functions available. Say that we add a DING instruction which plays a little sound every time it’s executed:

_(MUL,        ABC) /* R(A) = RK(B) * RK(C) */\
_(DING,       Buu) /* A = sound number to play */\
...

There’s now a new operation identifier available called S_OP_DING as well as constructor function for encoding DING instructions:

SInstr  SInstr_DING(uint32_t value);

Running a program now that includes a DING operation will cause an error in the VM: “unexpected operation”. We haven’t implemented the DING behavior yet! Operations are (at the time of writing this) implemented in sched_exec.h which is the core of the virtual machine as this is what reads and performs the instructions of a Sol program. It can be summed up like this:

void Execute(Instr* instructions) {
  Instr* pc = instructions;
  while (1) {
    switch (*++pc) {
    case S_OP_LOADK:
      // Read operands A and B from instruction *pc.
      // Put constant at B into register A.
      break;

    case S_OP_MOVE:
      // Read operands A and B from instruction *pc.
      // Put value of register B in register A.
      break;

    ...

    } // switch
  } // while
}

Pretty much a good old switch loop. When this C code is compiled with a modern compiler like Clang or GCC, it will be rather efficient as each of our virtual operations effectively corresponds to only a few machine instructions. This is where we need to add DING.

    ...
    case S_OP_DING:
      // Read operand Buu from instruction *pc.
      uint32_t sound_index = SInstrGetBuu(*pc);
      // Find note for sound_index and play it
      SoundNote* note = SoundGetNote(sound_index);
      SoundPlay(note);
      break;
    ...

Here the type Sound as well as SoundGet and SoundPlay represents some kind of sound playing function that you provide. Now we can write Sol programs that play music:

define melody 0
  entry:
  DING   0      # play note 0
  DING   1      # play note 1
  DING   1      # play note 1
  DING   2      # play note 2
  DING   0      # play note 0
  RETURN 0  0   # return

Pling, plong, plong, ding, pling!

Multitasking

No toy VM can be presented without shame unless it’s able to multitask; perform multiple things at once, or at least give the programmer the illusion of concurrency.

Sol has an operation called “yield” which is able to pause a task in any state and later have that task resume at the exact same state.

From the task’s perspective it never knew it was paused and resumed. This is a powerful primitive as we can implement many features on top of this. At the time of writing, Sol already has two different types of yield: Yielding for other tasks (so they can run or be scheduled from I/O etc events), and yielding for a timer to expire. At the end of this article there are a few example programs, all of them making use of yield.

Yield is used to implement cooperative multitasking where all tasks cooperate for the use of processing resources. When a task has performed a series of computations and relieves control to another task, one of three things has happened:

The task initiated an external (“blocking”) operation, like reading from a file or waiting for a certain time to occur,
the task completed and ended (it’s “main” function returned.),
or the task faulted, caused an error.

Most systems that communicate with its environment and abroad, like a web server or a text editor, spend most of its time (CPU time relative to real time) waiting for the environment to respond; e.g. producing data on a network socket, writing contents to a file or returning a stepper motors position. These systems often benefit from cooperative multitasking, in particular coherent, specialized systems (unlike operating systems which are general by nature).

What Sol provides is essentially coroutines for concurrency. A nice feature with coroutines (aka “green threads” aka “user threads”) is their ability to run sequential code in a concurrent system. A task like this:

def read_file(name):
  f = open(name)
  data = read(f)
  close(f)
  return data

Involves three “blocking” calls to the environment which causes the task to yield:

open asks the operating system to open a file by name. The file might get opened sometime in the future. The scheduler takes a note that the task is waiting for this to happen, removes it from the run queue for the time being.
The OS tells the scheduler that “that file you wanted me to open, well here’s the file descriptor” and thus the scheduler places the task on the run queue again.
The task receives the file descriptor representing the opened file
The task again calls to the environment, this time asking to read the contents of f.
Same thing as before, the scheduler tells the OS, takes a note, unschedules the task and continue with executing other tasks.
The OS tells the scheulder “I’ve read that file you asked me to read, here’s the data” (in reality this is slightly more complicated, but the principles are the same)
The scheduler queues the task, runs it.
Same thing with the close function.

For the programmer it’s easy to follow the flow of her program.

Comparing the above synchronous program to an asynchronous version:

def read_file(name, callback):
  open(name, def (error, f):
    if (error):
      callback(error)
    else:
      read(f, def (read_error, data):
        close(f, def (error):
          callback(error, data)
        )
      )
  )
  # returns here before the file has been opened

Clearly harder to follow. A task in Sol can spawn new tasks in order to perform several things at the same time, like writing a file while replying over the network.

def write_and_reply(destination_id, message):
  writer = write_file(destination_id + ".msg", message)
  send_message(destination_id, message)
  while (recv(writer) != TaskEnd) noop  # wait for write_file to end

However, as the Wikipedia section on cooperative multitasking mentions…

Because a cooperatively multitasked system relies on each process regularly giving up time to other processes on the system, one poorly designed program can consume all of the CPU time for itself or cause the whole system to hang.

This can happen when a program performs a very lengthy set of computations and can cause all kinds of problems, especially for other tasks relying on timers. As the Sol scheduler checks for timer expiration only between execution of tasks, a timer might effectively fire long after it was supposed to. Imagine controlling a toy quadrotor where one task needs to update one rotor’s angle each 50 milliseconds, and another task consumes a wholesome 200 milliseconds, then your quadrotor might just crash and burn.

To address this Sol employs an operation cost counter. Each task is given a predefined amount of “operation value” per execution iteration (when the scheduler runs a task’s program). When the operation cost counter reaches its limit, the task is simply forced to yield to other tasks. In the source code, look for S_VM_EXEC_LIMIT.

Some examples

The code below is expressed in a simplified assembly language that is almost 1:1 with the C API for defining these programs programatically, and so the assembly language itself should be considered irrelevant beyond explaining the instructions executed.

In the output, lines like these: [vm] ______________ ... denote when the scheduler regains control after running a task and the task either returned or yielded. This is one “execution iteration”. When running multiple tasks, you will usually see tasks interleved in round-robin order between these “execution iteration” marker lines.
In the output, lines starting with “…” are comments and/or simplifications and not part of the actual output.
In assembly comments, R(x) means “Register x”, RK(x) means “Register x if x is less than k else Constant (x-k)” where k is a special value, K(x) means “Constant x”.
In assembly comments, PC signifies the “program counter” which is sort of a cursor to the instructions of a program. It is incremented by one for each instruction executed. Some instructions will further modify this counter, like for instance the JUMP instruction.

Example 1: while x > 0 yield …

While the variable x is greater than zero, decrement x by one and yield to the scheduler, letting other tasks run. Eventually return.

def main():
  x = 5
  while (x > 0):
    x = x - 1
    yield
  return

Assembly:

define main 0
  CONST 5           # K(0) = 5
  CONST 0           # K(1) = 0
  CONST 1           # K(2) = 1
  entry:
  LOADK  0  0       # R(0) = K(0)
  LE     0  0  256  # (0 == RK(k+1) < RK(0)) ? continue else PC++
  JUMP   3          # PC += 3 to RETURN
  SUB    0  0  257  # R(0) = R(0) - RK(k+1)
  YIELD  0  0  0    # yield A=type=sched
  JUMP   -5         # PC -= 5 to LE
  RETURN 0  0       # return

Output when running in debug mode:

$ build/debug/bin/sol
Sol 0.1.0 x64
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 0          LOADK   AB:    0,   0
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 3          SUB     ABC:   0,   0, 257
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 4          YIELD   ABC:   0,   0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 5          JUMP    Bss:       -5
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 3          SUB     ABC:   0,   0, 257
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 4          YIELD   ABC:   0,   0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
...three more execution iterations identical to the above block...
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 5          JUMP    Bss:       -5
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 2          JUMP    Bss:        3
[vm] 0x7fdf28c03c00 0x7fdf28c000e0 6          RETURN  AB:    0,   0
Scheduler runloop exited.

Example 2: Function calls and timers

This program uses two functions. The entry point is the main function which simply calls the kitten function with one argument ‘500’. The kitten function “sleeps” for the number of milliseconds passed to it (as the first argument.) The kitten function then returns the number “123” to the caller—the main function—which dumps register values and finally returns, causing the task to exit and subsequently the scheduler and the VM too to exit.

Assembly:

define kitten 1     # Arguments: (R(0)=sleep_ms)
  CONST  123        # K(0) = 123
  entry:
  YIELD  1  0  0    # yield A=type=timer, RK(B)=R(0)=arg0
  LOADK  0  0       # R(0) = K(0) = 123
  RETURN 0  1       # return R(0)..R(0) = R(0) = 123

define main 0       # Arguments: ()
  CONST  @kitten    # K(0) = <func kitten>
  CONST  500        # K(1) = 500
  entry:
  LOADK  0  0       # R(0) = K(0) = the kitten function
  LOADK  1  1       # R(1) = K(1) = 500
  CALL   0  1  1    # R(0)..R(0) = R(0)(R(1)..R(1)) = a(R(1))
  DBGREG 0  1  0    # VM debug function that dumps register values
  RETURN 0  0       # return

Output when running in debug mode:

$ time build/debug/bin/sol
Sol 0.1.0 x64
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7f8c9bc03bf0 0x7f8c9bc03910 0          LOADK   AB:    0,   0
[vm] 0x7f8c9bc03bf0 0x7f8c9bc03910 1          LOADK   AB:    1,   1
[vm] 0x7f8c9bc03bf0 0x7f8c9bc03910 2          CALL    ABC:   0,   1,   1
[vm] 0x7f8c9bc03bf0 0x7f8c9bc000e0 1          YIELD   ABC:   1,   0,   0
D Timer scheduled to trigger after 500.000000 ms (sched.c:81)
# ...time passes and in this case the scheduler is idling...
D Timer triggered -- scheduling task (sched.c:57)
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7f8c9bc03bf0 0x7f8c9bc000e0 2          LOADK   AB:    0,   0
[vm] 0x7f8c9bc03bf0 0x7f8c9bc000e0 3          RETURN  AB:    0,   1
[vm] 0x7f8c9bc03bf0 0x7f8c9bc03910 3          DBGREG
D [vm] R(0) = 123.000000 (sched_exec.h:214)
D [vm] R(1) = 500.000000 (sched_exec.h:215)
D [vm] R(0) = 123.000000 (sched_exec.h:216)
[vm] 0x7f8c9bc03bf0 0x7f8c9bc03910 4          RETURN  AB:    0,   0
Scheduler runloop exited.

real  0m0.504s
user  0m0.001s
sys   0m0.001s

Example 3: Multitasking

Here we run three tasks, each running the program in Example 1:

$ build/debug/bin/sol
Sol 0.1.0 x64
[sched 0x7fc219403930] run queue:
  [task 0x7fc219403c00] -> [task 0x7fc219403cd0] -> [task 0x7fc219403da0]
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403c00 0x7fc2194000e0 0          LOADK   AB:    0,   0
[vm] 0x7fc219403c00 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403c00 0x7fc2194000e0 3          SUB     ABC:   0,   0, 257
[vm] 0x7fc219403c00 0x7fc2194000e0 4          YIELD   ABC:   0,   0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403cd0 0x7fc2194000e0 0          LOADK   AB:    0,   0
[vm] 0x7fc219403cd0 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403cd0 0x7fc2194000e0 3          SUB     ABC:   0,   0, 257
[vm] 0x7fc219403cd0 0x7fc2194000e0 4          YIELD   ABC:   0,   0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403da0 0x7fc2194000e0 0          LOADK   AB:    0,   0
[vm] 0x7fc219403da0 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403da0 0x7fc2194000e0 3          SUB     ABC:   0,   0, 257
[vm] 0x7fc219403da0 0x7fc2194000e0 4          YIELD   ABC:   0,   0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403c00 0x7fc2194000e0 5          JUMP    Bss:       -5
[vm] 0x7fc219403c00 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403c00 0x7fc2194000e0 3          SUB     ABC:   0,   0, 257
[vm] 0x7fc219403c00 0x7fc2194000e0 4          YIELD   ABC:   0,   0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
# The above block of instruction is repeated three times in interleved
# round-robin order for each task. Then:
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403c00 0x7fc2194000e0 5          JUMP    Bss:       -5
[vm] 0x7fc219403c00 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403c00 0x7fc2194000e0 2          JUMP    Bss:        3
[vm] 0x7fc219403c00 0x7fc2194000e0 6          RETURN  AB:    0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403cd0 0x7fc2194000e0 5          JUMP    Bss:       -5
[vm] 0x7fc219403cd0 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403cd0 0x7fc2194000e0 2          JUMP    Bss:        3
[vm] 0x7fc219403cd0 0x7fc2194000e0 6          RETURN  AB:    0,   0
[vm] ______________ ______________ __________ _______ ____ ______________
[vm] Task           Function       PC         Op      Values
[vm] 0x7fc219403da0 0x7fc2194000e0 5          JUMP    Bss:       -5
[vm] 0x7fc219403da0 0x7fc2194000e0 1          LE      ABC:   0,   0, 256
[vm] 0x7fc219403da0 0x7fc2194000e0 2          JUMP    Bss:        3
[vm] 0x7fc219403da0 0x7fc2194000e0 6          RETURN  AB:    0,   0
Scheduler runloop exited.

Source code

Released free under a very permissive MIT-style license at https://github.com/rsms/sol.

Our own little computer language

2012-10-07T00:00:00+00:00

Let’s write our own programming language. It’ll be fun and we will learn some key tools for processing structured data, performing semantic analysis, how to make a computer execute code, and all this using modern JavaScript.

We will create five major components, each outlined in a separate article:

Lexical analyzer
Semantic parser
Code generator
Management and support
Runtime library

Today we will actually do two things: Define a first version of our language’ lexicon, and write a lexical analyzer—or lexer—which performs lexical analysis of our language. From Wikipedia:

lexical analysis is the process of converting a sequence of characters into a sequence of tokens. A program or function which performs lexical analysis is called a lexical analyzer, lexer, or scanner.

Our lexer will understand the basic building blocks of our language, similar to what a word and punctuation are in natural language text. Naturally we need to decide which these words and punctuation are. I think this is one of the most fun parts of writing your own language, as we are completely free to design our language.

A lexer is usually the first part in the evaluation pipeline:

Source code → Lexer → Parser → Code generator → Execution

Language lexicon and syntax

Let’s formulate the basic building blocks of our language. Before we write anything, let’s take a minute and think about what kind of language we wish to design. We don’t have to commit to anything yet, but it will be easier for us to make progress if we have an idea of what we are trying to accomplish.

If we have the answers to the following to questions, our work will be easier.

Are linebreaks significant?
Is leading whitespace significant?

A language like C does not care about whitespace at all, except for separating keywords, whilst a language like Python cares about both linebreaks and leading whitespace. Let’s say “yes” to both these questions. Our language might care about both linebreaks and leading whitespace.

Syntax

Here’s a BNF-style sketch of the language I have in mind for this tutorial. Feel free to make up your own version.

Expression           = ExpressionGroup | Number | Text | Path | List | Map
ExpressionGroup      = "(" Expression* ")"
Line                 = Linebreak Space*

Whitespace           = Linebreak | Space
Linebreak            = U+000A..U+000D | U+0085 | U+2028 | U+2029
Space                = U+0009 | U+0020 | U+00A0 | U+180E | U+2000..U+200B
                     | U+202F | U+205F | U+3000 | U+FEFF

Number               = IntegerNumber | HexIntegerNumber | FractionalNumber
IntegerNumber        = DecimalDigit+
DecimalDigit         = 0..9
HexIntegerNumber     = "0x" HexDigit+
HexDigit             = 0..9 | A..F | a..f
FractionalNumber     = DecimalDigit+ "." DecimalDigit* FractionExponent?
FractionalExponent   = ("E" | "e") ("-" | "+")? DecimalDigit+

Text                 = "'" TextCharacter* "'"
TextCharacter        = U+0021..U+0026
                     | U+0028..U+005B
                     | "\" TextEscCharacter
                     | U+005D..U+FFEE
TextEscCharacter     = "\" | "'" | "t" | "n" | "r" | UnicodeValue
UnicodeValue         = "u" HexDigit{4} | "U" HexDigit{8}

Path                 = Symbol ("." Symbol)*
Symbol               = <SymbolCharacter except 0..9> SymbolCharacter*
SymbolCharacter      = <VisibleCharacter except SingleTerminator>
VisibleCharacter     = <UnicodeCharacter except Whitespace | ControlCharacter>
UnicodeCharacter     = U+0000..U+FFFE
ControlCharacter     = U+0000..U+0020 | U+007F..00A0 | U+FFEF..U+FFFF
SingleTerminator     = "(" | ")" | "." | ":" | "[" | "]" | "{" | "}"

List                 = "[" Expression* "]"

Map                  = "{" MapPair* "}"
MapPair              = MapKey ":" Expression
MapKey               = Symbol | Text

This format, usually referred to as BNF (although not actual strict BNF), is a way of expressing a syntax in terms of simple reductions. A quick guide to general BNF format:

Foo = Bar | Baz — “Foo” means either exactly one Bar or exactly one Baz.
Bar? — Zero or one “Bar” (a trailing “?” means “optional”)
Bar* — Zero or more “Bar” in succession
Bar+ — One or more “Bar” in succession
Bar{4} — Exactly 4 “Bar” in succession
A..F — Exactly one of the items in the natural sequence (here, A, B, C, D, E or F)
"Bar" — The literal “Bar”
(A | B) C — “(“ and “)” groups an anonymous reduction, here meaning “one of A or B, then one C”
U+2192 — A Unicode character value (in this case the RIGHTWARDS ARROW codepoint)
<Foo except A and C> — Simplification of a reduction of “Foo”. Generally not recommented but useful in early stages of design.

The above language is definitely incomplete (no functions or operators), but is a great start and to be honest it’s more than we need to get started. It would allow source code like this:

Hello = (bar baz) ->
  ה = can-haz [bar 'bar bara']
  54.8 * ה

The first step to interpreting this code is to perform lexical analysis. As discussed earlier this means that a stream of bytes is the input and a stream of tokens is the result. Given our partial language specification, the above source should produce the following tokens:

Symbol("Hello"), Symbol("="), LeftParen, Symbol("bar"), Symbol("baz"), RightParen, Symbol("->"), Line(with 2 spaces),

Symbol("ה"), Symbol("="), Symbol("can-haz"), LeftSquareBracket, Symbol("bar"), Text("bar bara"), RightSquareBracket, Line(with 2 spaces),

FractionalNumber("54.8"), Symbol("*"), Symbol("ה"), Line(with 0 spaces)

With our current language lexicon and syntax we are able to formulate more complex structures that the above example, for instance:

Text.join = (list-of-text glue) ->
  result = nil
  for text in list-of-text
    result = if (result == nil) text
             else result + glue + text
  result

(print (Text.join ['Yet another' 'Hello' 'world'] ' '))

However, let’s stick to the previous simpler example for now.

This is an excellent time to take a break and play around with some different imaginary language syntax. Remember that the lexer only needs to know about what a word is not all the possible words or even the sequence of words. When I say “words” here I mean the smallest building blocks of the syntax, or tokens as they are usually called. Let’s call each small unit of meaning a “token” from here on forward.

Behold, a lexer

Remember the evaluation pipeline?

Source code → Lexer → Parser → Code generator → Execution

Parsing and dealing with code is inherently a flowing system with no specific beginning or end. Sure, if we read the source from a file the file will have a start and it will have an ending, but let’s write a pipeline that is universal and has incremental functionality. In contrary to traditional batch lexers, an incremental lexer is able to iteratively analyze a continuous stream of characters and with little delay produce tokens on-the-fly. The tokens produced by our lexer will even be able to retain a persistent “snapshot” of the lexer’s state, for the abilitly to perform an incremental modification from a certain point. However, our lexer will merely make this possible but not directly provide this functionality.

Given these requirements of being able to pause, resume and change source as we are producing tokens, there are not many implementation approaches available to us. In a language that has functions with local variables (usually implemented with a stack) a batch lexer can be efficiently implemented with a function-based recursive decent approach, where each token reduction (see our BNF-style language definition) is represented by a function that calls another function depending on the source character at hand.

Here is pseudo-code implementing a recursive decent approach (this particular one is actually not recursive, but could very well become so), able to handle the Text part of our syntax:

class Lexer:
  next_char = nil
  input = ""
  input_offs = 0

  def ReadToken():
    return this.ReadExpression()

  def ReadExpression():
    if this.next_char == "'":
      this.ReadNextChar() # Consume "'"
      return this.ReadText()
    else if ...

  def ReadText():
    token = {type = TEXT, value = ""}
    prev_was_escape = false
    while this.next_char:
      if prev_was_escape:
        prev_was_escape = false
        token.value = concat(token.value, this.next_char)
      else if this.next_char == "\\":
        prev_was_escape = true
        continue
      else if this.next_char == "'":
        break
      else:
        token.value = concat(token.value, this.next_char)
    this.ReadNextChar() # Consume "'"
    return token

  def ReadNextChar():
    this.next_char = this.input[this.input_offs++]

L = Lexer()
L.SetInput("'Hello world'")
L.ReadToken()  # -> {type=TEXT, value="Hello world"}

This works fine for source input that is provided as one continuous sequence. If we were to pause a batch lexer like this, it would either imply a very complex and probably inefficient code which records and stuffs away the current call stack (essentially co-routines or green threads), or abort and retry from the beginning again later.

Say the source 'Hello world' arrives in two chunks and we try to apply the above batch lexer:

SetInput("'Hello wo")
ReadToken()  # -> nil
# Some time passes...
SetInput("rld'")
ReadToken()  # -> something not a string

When ReadText is called, next_char will be nil before the loop sees a terminating “’” character, and since all state is kept on the stack it will be lost when the function returns. Thus the second call at line 4 and 5 will begin reading with a reset state. No cigar.

So we realized that the state of the lexer must be held by the lexer itself and in a way that can be represented persistently (e.g. as data in memory).

Looking again at the pseudo code above for a batch lexer, we will look at what actually happens by unrolling the code:

The lexer is asked to read the next token
At this point the lexer has no context so the only thing it can do is to parse an “Expression”. Calling the “ReadExpression” function creates a new stack call entry. This is the state of what we are reading.
Okay, so we are reading an expression. Since we have no previous information about where in an expression we are, let’s look at the current character of the source code (it’s “’”)
Since the character is a “’” we know that a “Text” token is coming up. Call “ReadText” to enter a state of “reading text”.
Create a new token and store it into the variable token that is kept on the stack. We need to keep track of the previous character since “\c” and “c” means different things. This is also kept as a variable prev_was_escape living on the stack (or in the function’s scope, depending on the language we write this in, but whatever).
Look at the next character, look at prev_was_escape and append next_char to the token value as we read.

Essentially each step is a certain code branch that flow into other code branches depending on certain branch-related values. So let’s move those values into a “lexer context” object which we instead pass around between readings.

Let’s rewrite the previous batch lexer using this strategy.

def Lexer():
  return {input = "", input_offs = 0, token = nil, next_char = nil}

def ReadToken(L):
  result = nil
  while L.next_char:
    if L.token == nil:
      # Entry state
      if L.next_char == "'":
        L.token = {type = TEXT, value = "", prev_was_escape = false}
        ReadNextChar(L) # Consume "'"
      else:
        ...
    else if L.token.type == TEXT:
      if L.token.prev_was_escape:
        L.token.prev_was_escape = false
        token.value = concat(token.value, L.next_char)
      else if L.next_char == "\\":
        L.token.prev_was_escape = true
      else if L.next_char == "'":
        result = L.token
        delete result.prev_was_escape
        L.token = nil
      else:
        token.value = concat(token.value, L.next_char)
      ReadNextChar(L)
    else:
      ...
  return result

L = Lexer()
SetInput(L, "'Hello wo")
ReadToken(L)  # -> nil
SetInput(L, "rld'")
ReadToken(L)  # -> {type=TEXT, value="Hello world"}

We simply moved the state into a structure (referenced to as L above) which we pass around instead of storing the state values on the stack. The function calls were replaced by logical code branches. The token structure above is used to carry token code-branch specific state. This design not only performs better (in most languages) but it also meets our requirements of being able to be paused and resumed.

A JavaScript implementation

For this tutorial article series I’ve chosen JavaScript as it’s easily accessible, a very popular language, has built-in Unicode support (good since we are to be analyzing text) and runs almost anywhere.

Before writing or running any code, install Node.js — a free, modern and efficient JavaScript environment that let’s you run JavaScript programs in a terminal session (just like Python, Ruby, Perl or any other regular program). It takes just a minute to download and install, so don’t hesitate: nodejs.org/download.

Now, let’s have a look at the lexer. It’s easiest if you clone or fork the Git repository at https://github.com/rsms/prog-lang-tutorial and have a look in the “01-lexer” directory. There is a file called lexer-demo.js — a simple program that imports our lexer and applies some sample source. Essentially it imports the Lexer module and does something like this:

var L = Lexer(), token;
L.appendSource('Foo (bar baz)');
while ((token = L.next(source_ended))) {
  console.log(Lexer.TOKEN_NAMES[token.type], token);
}

The interesting part is in the lib/mylang/Lexer.js file, so let’s quickly look through the different sections of the Lexer code.

// Create a new Lexer object.
function Lexer() {
  return Object.create(Lexer.prototype, ...

This function creates new Lexer objects with initial state. We call this function each time we start reading a new source stream.

Next up is a set of token definitions. This is where we define each of the different token types that our language is constructed from.

var LINE                 = deftok('LINE');
var LEFT_PAREN           = deftok('LEFT_PAREN',           '(');
var RIGHT_PAREN          = deftok('RIGHT_PAREN',          ')');
var LEFT_SQUARE_BRACKET  = deftok('LEFT_SQUARE_BRACKET',  '[');
var RIGHT_SQUARE_BRACKET = deftok('RIGHT_SQUARE_BRACKET', ']');
var LEFT_CURLY_BRACKET   = deftok('LEFT_CURLY_BRACKET',   '{');
var RIGHT_CURLY_BRACKET  = deftok('RIGHT_CURLY_BRACKET',  '}');
var FULL_STOP            = deftok('FULL_STOP',            '.');
var COLON                = deftok('COLON',                ':');
var DECIMAL_NUMBER       = deftok('DECIMAL_NUMBER');
var HEX_NUMBER           = deftok('HEX_NUMBER');
var FRACTIONAL_NUMBER    = deftok('FRACTIONAL_NUMBER');
var SYMBOL               = deftok('SYMBOL');
var TEXT                 = deftok('TEXT');

The deftok helper function simply assigns the token a unique number identifier and if a second argument is given, associates that token id with a single character value (this is stored in the internal map SINGLE_TOKENS). The Lexer will be able to look up a character value in this map and if it’s there, immediately terminate any currently reading token. This is useful for single-character tokens which might appear immediately before or after for instance a symbol.

The Lexer prototype is the prototype of the object returned by the Lexer() function:

Lexer.prototype = {

appendSource is used to set/append source input:

  // Add input source.
  // The `chunk` object need to have the following properties:
  //
  //  .charCodeAt(N)   A function that return the Unicode character value at
  //                   position N, or a NaN if N is out of bounds.
  //
  //  .substring(A, B) A function that returns another chunk object that
  //                   represents the Unicode characters in the range [A,B)
  //
  appendSource: function (chunk) { ...

makeToken is mean to be used only internally by other Lexer functions. This is called every time a new token is being read:

  // Create a new token of `type` based on the internal source location state
  makeToken: function (type) { ...

flushToken is also meant as an internal function which is called each time a token is about to be returned as a result from the next function:

  // Returns the current token and clears the "reading token" state. This is
  // an appropriate place to perform some post processing on tokens before
  // they are returned to the caller of `next()`. If `terminated_by_eos` is
  // true, the token was terminated by end of source.
  flushToken: function (terminated_by_eos) { ...

next is called to give control to the lexer and returns either when the lexer has read a token (a token is returned), when an error occurs (an exception is thrown) or the input source ended (null is returned).

  // Reads the next token. If `source_ended` is true, then no more source is
  // expected to arrive and thus EOS acts as a token terminator.
  next: function (source_ended) { ...

That’s it for a summary of the Lexer design. I suggest you look through the code which is thoroughly documented.

I’ve left one part unimplemented for you to write: Reading Text literals. Run the lexer-demo.js:

$ node lexer-demo.js
read_tokens(L)
L.next() -> SYMBOL 'Hello' at 0:0
L.next() -> SYMBOL '=' at 0:6
...
Error: Lesson 1: Implement reading of Text tokens
;)

Again, the source is available at https://github.com/rsms/prog-lang-tutorial.

In the next article we will look at how semantic parsing fits into the evaluation pipeline.

Factorial and Fib in Hue

2012-05-29T00:00:00+00:00

As I slowly make progress on my little functional programming language Hue, I’d just wanted to share the “Hello World” of functional programming — factorial and fib.

The factorial function calculates the factorial of a natural number:

factorial = func (n Int) if n == 0 1 else n * factorial n - 1
factorial 10  # -> 3628800

The fib function computes Fibonacci numbers:

fib = func (n Int)
  if n < 2
    n
  else
    (fib n-1) + fib n-2

fib 32  # -> 2178309

Hue compiles the above functions into very efficient tail calls. The factorial function is even unrolled, eliminating all but one call.

Function result type inference and multiple implementations

Since Hue 94441d9 functions have their result types inferred, as well as the ability to define multiple implementations.

To understand why the ability to provide multiple function implementations is interesting, let’s define a slightly more versatile factorial function:

factorial = func (n Int)
  if n == 0    1
  else         n * factorial n - 1

factorial = func (n Float)
  if n == 0.0  1.0
  else         n * factorial n - 1.0

Here, we provide implementations for factorial to operate on both integers and floating point numbers. We can now invoke factorial with both Ints and Floats:

factorial 10    # -> 3628800
factorial 10.0  # -> 3628800.0

Since Hue is strongly typed, simply providing a single implementation would only allow factorial to be available for either integers or floating point numbers (unless we gave the function different names, but that becomes awkward.)

Result type inference is another important hygiene factor.

This basically means that the parser will parse a function’s body before it finalizes the function’s result type. Since all functions in Hue return something, we know that whatever is returned is the result value of the function. If there’s any ambiguity the compiler will complain with an error, avoiding unexpected behavior at runtime.

Consider the following trivial functions:

foo = func (a, b Int) Int a * b * b
bar = func (a, b Float) Float a * a * b

Defining the result type of these functions is redundant and unnecessary, since we can without a doubt say that “the result type of function F is the type of the value returned”. As Hue infers the type not only for functions, but for any other non-primary expression (like conditionals), when we after a decent-first reach the surface of an expression (i.e. the last expression of a function body), we will know the type of that expression, thus we can bubble the type upwards.

foo = func (a, b Int) a * b * b
bar = func (a, b Float) a * a * b

As seen here above, we were able to write the same two functions in a more efficient manner.

If a function references itself (i.e. is recursive), Hue will assume the type of the function based on other known types and later update those functions calls when the function’s result type has been finalized.

Deferring the resolution of a recursive function type is possible since the only case where we are unable to do so, is the case where a recursive function is an infinite loop (which is currently not applicable to anything in Hue.) For instance:

foo = func (n Int) foo n

…would yield an error when compiled since it defines a function that is guaranteed to crash/block in all eternity. Any recursive function needs some kind of conditional, thus making our stupid foo function a little more useful:

foo = func (n Int) if n > 5 (foo n * n) else n

This will compile, although the program will still crash when foo is given a value higher than 5. That’s the balance between being helpful and telling you what to do. In this example, the result type of the conditional (the “if..else”) is inferred from the one concrete branch (“n”), which in turn completes the foo function’s result type.

Tail recursive calls FTW

Let’s get all nerdy and look at the IR produced by Hue for the factorial function example from the beginning of this article:

define i64 @main() nounwind readnone {
  br label %tailrecurse.i

tailrecurse.i:                                    ; preds = %else.i, %0
  %accumulator.tr.i = phi i64 [ 1, %0 ], [ %multmp.i, %else.i ]
  %n.tr.i = phi i64 [ 10, %0 ], [ %subtmp.i, %else.i ]
  %eqtmp.i = icmp eq i64 %n.tr.i, 0
  br i1 %eqtmp.i, label %"hello:factorial$x$x.exit", label %else.i

else.i:                                           ; preds = %tailrecurse.i
  %subtmp.i = add i64 %n.tr.i, -1
  %multmp.i = mul i64 %accumulator.tr.i, %n.tr.i
  br label %tailrecurse.i

"hello:factorial$x$x.exit":                       ; preds = %tailrecurse.i
  ret i64 0
}

Note how there’s actually no function calls involved here. The compiler (mostly thanks to LLVM) were able to optimize the recursive call by unrolling the calls. The above code is very efficient.

Let’s have look at what Hue does with the fib example function (from earlier in this article):

define i64 @main() nounwind readnone {
  %fib_res = tail call i64 @"hello:fib$x$x"(i64 32)
  ret i64 0
}

define private i64 @"hello:fib$x$x"(i64 %n) nounwind readnone {
  %lttmp = icmp slt i64 %n, 2
  br i1 %lttmp, label %endif, label %else

else:                                             ; preds = %0
  %subtmp = add i64 %n, -1
  %fib_res = tail call i64 @"hello:fib$x$x"(i64 %subtmp)
  %subtmp1 = add i64 %n, -2
  %fib_res2 = tail call i64 @"hello:fib$x$x"(i64 %subtmp1)
  %addtmp = add i64 %fib_res2, %fib_res
  ret i64 %addtmp

endif:                                            ; preds = %0
  ret i64 %n
}

We didn’t get the royal unroll treatment, but the calls became tail recursive and the true-branch of the conditional expression was short-circuited into the end of the conditional (“endif”), saving us a “PHI” virtual instruction. This code is also very efficient and has linear time complexity.

Hue continues to be my computer programming muse (and TV substitute) as a low intensity hobby project. The intention is to experiment with performant functional programming and to learn stuff, of course. Hue’s source code is free and open at https://github.com/rsms/hue.

See previous introduction to Hue: “Hue — a functional programming language for fun & play”.

Hue — a functional programming language for fun & play

2012-05-14T00:00:00+00:00

Hue is one of my latest hobby projects that didn’t die after a week. It’s a functional programming language, in a sense. There are no statements in this language, but everything is an expression. An expression does something funky and returns something—hopefully—even funkier. That includes if..then..else as well as logical tests and functions.

Anyhow, this hobby language of mine is still very much in flux and I’ll probably change its syntax and behavior a few times before I’m really happy with it. Haskell, Erlang and Clojure all have some pretty cool features but I’ve never been friends with their syntaxes. Me wants something closer to Python. Me write language.

A programming language is in its essence a Human-Computer Interface. I’ve done these things in the past, for example the Move programming language. This time I wanted to write everything myself, starting at the instructions that the computer executes and all the way up to the runtime library, idioms, design opinions and concepts.

So far I’ve spent evenings and weekends during the last five weeks hacking on this, bust more so I’ve been reading conceptual stuff, like Joe Armstrong’s thesis paper “Making reliable distributed systems in the presence of software errors” (chapters 1 and 2), where Joe dissects the inherent problems with trying to model the real world using a non-1:1 mapping (e.g. imperative programming that fakes concurrency) and so forth.

From Hue to target assembly

A simple and completely useless program that contains a function which multiplies two integers with 9 and each other, then divides that with 4 and returns the result:

foo = ^(x, y Int) Int: z = x * y * 9
                       z / 4
a = 19
b = foo 4 (5*10*a)  # => 8550

Note a few things:

Whitespace is significant. Like in the Python programming language, a colon “:” character denotes that a block of expressions follow. When the line indentation level drops from whatever level the expression that owns the “:” character is at, the block is terminated. The foo function’s block contains two expressions.
Types are inferred. The language is strongly typed and in case the compiler is unable to infer the type, it will yield a compilation error. No types are inferred at runtime, which means that very few—or even no—errors related to types and value passing can happen when the program is run.
Functions are expressions and not a “special” thing. Functions can be passed around just like any other value.
Variables are actually just aliases and usually “folded” (removed and their values is just put in place) by the compiler.

Let’s compile this program:

hue hello.hue hello.ll

And look at the LLVM IR code that the Hue compiler generates:

define i64 @main() nounwind {                               ; 1
  %foo_res = call i64 @"hello$foo"(i64 4, i64 950)          ; 2
  ret i64 0                                                 ; 3
}

define private i64 @"hello$foo"(i64 %x, i64 %y) nounwind {  ; 4
  %multmp = mul i64 %x, %y                                  ; 5
  %multmp1 = mul i64 %multmp, 9                             ; 6
  %divtmp = sdiv i64 %multmp1, 4                            ; 7
  ret i64 %divtmp                                           ; 8
}

The Hue compiler generates LLVM intermediate representation code. Similar to what is output by e.g. Java and .NET compilers when an object file/program is built. LLVM is an amazing piece of compiler infrastructure software that enables a whole slew of features like native machine code generation, code optimization, etc. Going back to the above IR code, we see what actually happened to our program. I’ve given the lines above numbers, which we are referring to here:

@main() is the entry point of our module. Or program in this case.
We call the function hello$foo with two 64-bit integer values 4 and 5. We expect a return value that is a single 64-bit integer value, which we give the alias “%foo_res”. Notice how the a = 19 and (5*10*a) expressions where folded into 950 (“i64 950” in the IR above). Because values are constant, the compiler can “execute” obvious isolated parts of the program.
Our module returns control, with the 64-bit integer value 0, to whatever called it (in this case, our program exists with status 0).
This is where our function lives. “private” means that the function is only used inside this module, and “i64” means it returns a 64-bit integer value (Hue’s “Int” type is a 64-bit integer). The function takes two parameterized arguments which both are 64-bit integers and gives those parameters the aliases “%x” and “%y”.
We ask the computer to multiply the two values behind the aliases “%x” and “%y” and give the resulting value an alias of “%multmp”.
Again, we instruct the computer (these are so called “instructions”) to multiply two values: The result of multiplying “%x” and “%y”, which we did at line 5, with the number 9 and alias the result as “%multmp1”.
We divide the “%multmp1” value with the number 4 and alias the result as “%divtmp”.
We return the value behind “%divtmp” to the caller.

If we generate assembly for x86_64 (basically machine instructions), we get roughly the following:

  .section __TEXT,__text,regular,pure_instructions
  .globl  _main
  .align  4, 0x90
_main:                          ; 1
  pushq   %rax
  movl    $4, %edi              ; 2 (1/4)
  movl    $950, %esi            ; 2 (1/4)
  callq   L_hello$foo           ; 2 (1/4)
  xorl    %eax, %eax            ; 3 (2/3)
  popq    %rdx                  ; 3 (3/3)
  ret                           ; 3 (4/3) ...
  .align  4, 0x90
L_hello$foo:
  imulq   %rsi, %rdi
  leaq    (%rdi,%rdi,8), %rcx
  movq    %rcx, %rax
  sarq    $63, %rax
  shrq    $62, %rax
  addq    %rcx, %rax
  sarq    $2, %rax
  ret

Yeah, I know. This code gets scarier and scarier, but we can see how closely LLVM IR maps to target assembly, but we also understand the complexity of modeling something simple as the initial Hue program on x86_64 assembler.

We can run our program, which by the way doesn’t really do anything, either straight through LLVM as JIT-ed code using lli hello.ll or generate an object file and link it as a program:

llvm-as -o=- hello.ll | llvm-ld -native -o=hello -
./hello

Functional programming has for a long time been the toolbox of mathematicians and CS ninjas with beards (Johan and Erik — I’m lookin’ at you). My guess is that math people—clever fellas—invented these things and created syntaxes that fell natural to them. I never really payed attention to math in school and have no math education beyond the very basics, like multiplication, yet I have come to realize the awesomeness of math and its concepts. So how about we take the awesomeness of functional programming—high modularity and code re-use, testability, stability, etc—to us programming peasants of Python, JavaScript, BASIC and Java? Perhaps this project will be an attempt on that, or perhaps not.

A performant immutable & persistent vector implementation

Besides rambling about some yet-another-hobby-language, I wanted to talk about this one awesome, concrete thing that has come out of this project: An immutable persistent vector inspired by and partly ported from Clojure’s PersistentVector. With this approach, you can freely manipulate a vector data structure concurrently without locking and more importantly without causing imperative situations where expected state is different depending on outside, out-of-our-control circumstances.

Impressive numbers: Starting with the empty vector and appending one single item at a time until we reach one million takes roughly 200ms on a single 3.4 GHz i7 core. That is an average of 200 nanoseconds per append operation. Keep in mind that an append operation effectively creates a new vector — this data structure is in fact immutable, so we have to create a new, derived structure every time we “modify” it. With a traditional array-style structure, where we have N items in a uniform sequence, is cheap to copy when N is reasonably small (like 100 or so), but becomes a real bottleneck (and a problem for concurrent operations) when N grows.

Now, writing to and updating vectors are usually less common that accessing items in them. Pretty convenient then that this implementation offers almost-constant time random access. Technically is a little less than constant, but it’s negligible in my opinion (see comments in Vector.h for more info).

The source for this implementation is available from the Hue GitHub repository together with some unit tests (look in the “test” directory or run the “test” make target).

Numbers from running make clean test_vector_perf:

N = 100 (this run takes the unfortunate initial impact of lazy-loaded symbols)
- Inserting 100 values: 0.028 ms (avg 280 ns/insert)
- Accessing all 100 values: 0.002 ms (avg 20 ns/access)
N = 100 000
- Inserting 100000 values: 20.722 ms (avg 207.22 ns/insert)
- Accessing all 100000 values: 0.531 ms (avg 5.31 ns/access)
N = 1 000 000
- Inserting 1000000 values: 204.391 ms (avg 204.391 ns/insert)
- Accessing all 1000000 values: 5.171 ms (avg 5.171 ns/access)
N = 10 000 000
- Inserting 10000000 values: 2002.78 ms (avg 200.278 ns/insert)
- Accessing all 10000000 values: 59.592 ms (avg 5.9592 ns/access)
N = 100 000 000
- Inserting 100000000 values: 19741.9 ms (avg 197.419 ns/insert)
- Accessing all 100000000 values: 674.349 ms (avg 6.74349 ns/access)

We can reason that for N up to at least 100 million, both insertion and random access is close to constant time complexity. It’s not nearly as fast as a traditional mutable vector which grows uniform regions of memory (e.g. std::vector or a plain C array), but given it’s immutable property, this is very good.

Source code and other goodies are available at github.com/rsms/hue.