24 May 2020, 18:28

AssemblyScript: Passing Data to and From Your WebAssembly Program

AssemblyScript takes a strict subset of TypeScript and allows it to be compiled to WebAssembly. This is a very persuasive selling point for developers familiar with JavaScript and TypeScript as it immediately allows them to transfer their skills to be able to write WebAssembly programs. This is exciting as WebAssembly has proved useful from things like game engines such as Unity to design tools such as Figma.

In this short blog post, we will look at how you can pass data from JavaScript to WebAssembly programs created using AssemblyScript. This blog will assume you’ve followed the quick start guide and that you are familiar with npm and JavaScript.

As it currently stands the only types WebAssembly supports are integers and floats, which are stored in linear memory (a single contiguous address space of bytes) for the WebAssembly program. As a language, AssemblyScript works with us in abstracting away some of the complexity of managing more complex types like strings and arrays. A common use-case for AssemblyScript might be to write a WebAssembly module and then make use of that within a JavaScript runtime. At some point, it will probably be necessary to pass some data from the JavaScript code to the WebAssembly module and/or back again. Let’s take a look at how we go about passing various data types to AssemblyScript.

Numbers

Passing numbers to our program is straightforward and doesn’t require any special treatment. We can achieve this by just passing them number values directly to our WebAssembly module function. You can use i32 your AssemblyScript code for intergers and f32 for float types, like so:


    // AssemblyScript
    export function add(a: i32, b: i32): i32 {
      return a + b;
    }

    export function addFloats(a: f32, b: f32): f32 {
      return a + b;
    }


    // JavaScript
    {
        add,
        addFloats
    } = wasmModule.exports;

    const result = add(1, 2);
    // result will be 3

    const floatResult = addFloats(1.5, 2.5);
    // result will be 4

This is great, especially if we don’t need to deal with any other types. However if our program gets more complex we may need to start dealing with other types.

Introducing the loader

As mentioned previously, WebAssembly as it stands only deals with number types. So how can we go about passing JavaScript data types like strings and arrays to our WebAssembly programs? One solution is to to use the AssemblyScript loader which simplifies the process of loading more complex data types into the WebAssembly memory. The module provides a set of convenience functions to allow loading in types like strings and arrays into memory, returning their pointers. It also allows for the managing of their lifecycle via retaining and releasing them. To get started using the AssemblyScript loader lets install it into our project using npm:

npm install @assemblyscript/loader

Once we’ve compiled our AssemblyScript program to a wasm file, we will want to use this in our web application.

Let’s start with how we go about instantiating our program (here we will be in a Node environment):


    const loader = require("@assemblyscript/loader");
    const buf = fs.readFileSync('./build/optimized.wasm');
    const wasm = new WebAssembly.Module(new Uint8Array(buf));
    loader.instantiate(wasm, { 
      env: { 
        abort: (err) => {
          console.error(err)
        }
      }
    }).then((wasmModule) => {

      console.log(wasmModule.exports);
      // Code to use the instantiated wasm module

    });

Strings

For more complex types like strings, we can leverage the loader. Strings in AssemblyScript are immutable, and hence we can’t change a string once we’ve passed its pointer to the AssemblyScript function. We could, however, return a pointer to a newly constructed string value. In this case, we’ll replace ‘hello’ in a string with ‘hi’ in the string and return a new string pointer, and then read it with the __getString method:


    // AssemblyScript
    export function replaceHelloWithHi(a: string): string {
      return a.replace("hello", "hi");
    }


    // JavaScript
    {
        __retain, 
        __allocString,
        __release,
        replaceHelloWithHi
    } = wasmModule.exports;
    const originalStr = "hello world";
    const ptr = __retain(__allocString(originalStr));
    const newPtr = replaceHelloWithHi(ptr);
    const newStr = __getString(newPtr);
    __release(ptr);
    __release(newStr);
    console.log(newStr);
    // logs out 'hi world'

Arrays

If you have a regular untyped array in our JavaScript side, we’ll still need to allocate a typed array on the WebAssembly side, we can use the AssemblyScript i32 type for this. We can get its id using the idof function to get the ID. For Typed Arrays we can use the same approach use the appropriate Typed Array type, in this case, Int32Array. We use idof like so:


    // AssemblyScript
    export const i32ArrayId = idof<i32[]>()
    export const Int32ArrayId = idof<Int32Array>()

Now we have the IDs we can use them using the appropriate functions from the AssemblyScript loader. We will need to allocate an array in the module’s memory and retain it to make sure it doesn’t get collected prematurely. Let’s work through this for the example of summing an array:


    // AssemblyScript
    export function sumArray(arr: i32[]): i32 {
      let sum: i32 = 0;
      for (let i: i32 = 0; i < arr.length; i++) {
        sum = sum + arr[i];
      }
      return sum;
    }


    // JavaScript
    const { 
        __retain, 
        __allocArray,
        __release,
        i32ArrayId,
        Int32ArrayId,
        sumArray
    } = wasmModule.exports;


    // Untyped arrays

    const arrayPtr = __retain(__allocArray(i32ArrayId, [1, 2, 3]))
    const sum = sumArray(arrayPtr);

    __release(arrayPtr);

    // Now for TypedArrays

    const typedArrayPtr = __retain(__allocArray(Int32ArrayId, new Int32Array([1, 2, 3])))
    const typedSum = sumArray(typedArrayPtr);


    __release(typedArrayPtr);

Are there any other approaches?

The loader could is deliberately quite minimalist and not as abstracted as they potentially could be. If you are looking for something simpler, I would definitely recommend taking a look at Aaron Turner’s asbind library which steamlines the process. For example, we can reduce the string example to the following code:


    // JavaScript
    import { AsBind } from "as-bind";
    const wasm = fs.readFileSync("./build/optimized.wasm");

    (async () => {
      const asBindInstance = await AsBind.instantiate(wasm);

      const response = asBindInstance.exports.replaceHelloWithHi("Hello World!");
      console.log(response); // Hi World!
    })();

08 May 2020, 18:28

Writing Web Workers in TypeScript

TypeScript has taken the web development world by storm, and I too am a fan. Unfortuantely what I’m not a fan of is contention on the main thread, which has increased over time as we ship more and more JavaScript to our pages.

I’ve written in previous posts about Web Workers, but for those of you note familiar they allow the developer to move work off of the main thread and into a separate thread of execution. These work great for tasks that often block such as data crunching in audio, gaming and mapping applications. We can also leverage them for more generic work, and Surma has done a great job of explaining why that is an important consideration for web developers.

In this post, I want to show how you can write Workers in TypeScript and build them using the popular bundler Webpack. The first step we need to take is to install all the modules we need via npm as development dependencies. We can do this from our command line like so:


We also need to set up a TypeScript configuration, `tsconfig.json`, file in our root directory.  We can do a rudimentary implementation like this:

```javascript
{
    "compilerOptions": {
      "outDir": "./dist/",
      "noImplicitAny": true,
      "module": "es6",
      "target": "es5",
      "allowJs": true,
      "sourceMap": true
    }
}

You can adjust this to your required tastes but this is a barebones starter to get going. Next lets setup the webpack.config.js file again in our root directory to configure Webpack and allow us to build our application and worker:

const path = require('path');

module.exports = {
    mode: 'development',
    entry: './src/index.ts',
    devtool: 'inline-source-map',
    module: {
        rules: [
            // Handle TypeScript
            {
                test: /\.tsx?$/,
                use: 'ts-loader',
                exclude: [/node_modules/]
            },
            // Handle our workers
            {
                test: /\.worker\.js$/,
                use: { loader: 'worker-loader' }
            }
        ]
    },
    resolve: {
        extensions: ['.ts', '.js']
    },
    output: {
        // This is required so workers are known where to be loaded from
        publicPath: '/dist/',
        filename: 'bundle.js',
        path: path.resolve(__dirname, 'dist/')
    }
};

This covers the build step side of things, now we can look at our code itself. Let’s assume we have a src folder for our source code, and a dist folder for a compiled code. The first thing we’ll want to do is setup types for the Workers so that TypeScript doesn’t complain:

// types.d.ts
declare module "worker-loader!*" {
    class WebpackWorker extends Worker {
      constructor();
    }
  
    export default WebpackWorker;
}

Now, let’s write a Worker. As an example of a large workload, this Worker will generate primes using the Sieve of Erastosthenes and return them back to the main thread:

// worker.js

// We alias self to ctx and give it our newly created type
const ctx: Worker = self as any;

class SieveOfEratosthenes {
    
    // This is the logic for giving us back the primes up to a given number
    calculate(limit: number) {

      const sieve = [];
      const primes: number[] = [];
      let k;
      let l;

      sieve[1] = false;
      for (k = 2; k <= limit; k += 1) {
        sieve[k] = true;
      }

      for (k = 2; k * k <= limit; k += 1) {
        if (sieve[k] !== true) {
          continue;
        }
        for (l = k * k; l <= limit; l += k) {
          sieve[l] = false;
        }
      }

      sieve.forEach(function (value, key) {
        if (value) {
          this.push(key);
        }
      }, primes);

      return primes;

    }

}

// Setup a new prime sieve once on instancation 
const sieve = new SieveOfEratosthenes();

// We send a message back to the main thread
ctx.addEventListener("message", (event) => {

    // Get the limit from the event data
    const limit = event.data.limit;

    // Calculate the primes 
    const primes = sieve.calculate(limit);

    // Send the primes back to the main thread
    ctx.postMessage({ primes });
});

And then back to our main thread we instantiate the worker and send a message asking the first 1000 primes:

// index.ts

// Not the worker-loader! syntax to keep Webpack happy
import PrimeWorker from "worker-loader!./worker";

const worker = new PrimeWorker();

worker.postMessage({ limit: 1000 });
worker.onmessage = (event) => {
    document.getElementById("primes").innerHTML = event.data.primes;
};

Now if we can build the file. Here we assign a build script "build": "webpack" in our package.json which will build the file for us into a dist directory as bundle.js. This can then be referenced inside your webpage of choice.

If you want to see the full working example I’ve posted it to this GitHub repository for you to experiment with.

29 Sep 2019, 21:28

Thinking Critically About Code Quality

I have been thinking recently about an aspect of software development which I feel can often be overlooked. The catalyst that triggered the thoughts in question was a post to Erlang mailing list from Joe Armstrong (the author of the Elang programming language). The email is titled with the subject ‘Why do we need modules at all?’. Joe’s post starts with a bold opening statement:

I’m proposing a slightly different way of programming here The basic idea is

  • do away with modules
  • all functions have unique distinct names
  • all functions have (lots of) meta data
  • all functions go into a global (searchable) Key-value database …

On it’s surface this completely flys in the face of an idea that as developers we get told is this axiomatic truth; global variables are bad. Although Joe’s post wasn’t really about code quality, it did get me thinking about it. We often have these ideals that we hold dear and hold others too in social rituals such as code reviews and meetup talks.

Yet for a profession that is steeped in correctness, exactitudes and objectivity, there are many elements of software development that are an aesthetic or cognitive preference. The classic case of this being tabs vs spaces. Indeed, it feels the growth and adoption of linters/formatters across languages and projects is not so much a pursuit to make a codebase more ‘correct’ but to sideline aesthetic and preferential ideals.

The longer I write code it seems to be more apparent that writing code is a near endless series of trade offs. The binary of ‘good’ and ‘bad’ code seems to break down when taking into account the writers constraints and the near limitless characteristics you could optimize for. To pick a few common ideals:

  • Correctness
  • Readability
  • Conciseness
  • Constency
  • Maintainability
  • Simplicity
  • Testability
  • Portability
  • Defensiveness
  • Performance
  • Security
  • Extensibility
  • DRYness
  • Modularity
  • Idiomatic

Not to mention that the meaning of these words is somewhat subjective, differ from (programming) language to language and are also transient. Is it possible to have code that is uniformly agreed to be ‘testable’ for example? Of course some of these characteristics are arguably more quantifiable or objective than others (e.g. performance), but even for these there will always be questions of which metrics and which results are acceptable.

So what does that mean in practice? I think it means accepting that no code will ever be ‘perfect’, that coding is a series of trade-offs, and that we need to decide what qualities we want to optimize for. If you’re writing a quick script at the weekend to rename some files, would you optimize for modularity and testability? Perhaps not. However, if you were writing production code in a team, the answer might be a little different. Maybe, as Joe did, sometimes it’s healthy to question beliefs that we hold strongly and ask if they always hold true (or if they are true at all). For example, is it always necessary to be DRY? Are their times it’s okay for things to be tightly coupled? What if we didn’t have 100% test coverage?

Do I think that the strive for code quality is redundant? Absolutely not. However, as I have grown as a developer it feels a fair portion of the things I was taught as universal truths about ‘good’ and ‘bad’ code seem to actually be socially reinforced norms. From a personal standpoint, I think it’s important to strive towards having a team outlook and agreement on what the meaning of ‘good’ code is. Taking this a step further maybe this means having it written down in a guide or even codified in linters/tool configs where possible. Here it feels that being empathetic and open-minded to others input are key to being successful in software, as the understandings of what constitutes good code differ from person to person. Perhaps the goal is treating coding collaboratively as an opportunity to learn from others and teach them, and less as an opportunity to assert an ideal of perfect code.