Paul Bone

3D Printing Diffusers for LED strips

Sat, 07 Feb 2026 00:00:00 +1100

This light is a 3D printed diffuser over a COB LED strip, and this post is how to make your own.

It also works for non-COB LED strips.

openGrid and Underware

Instead of uploading some models for you to print I’m going to refer to existing systems that we’re going to customise. The first is openGrid, a flexible-yet-simple wall storage system. It provides the square grid that everything else is clipped to. I used the "light" grid and screwed it into my wooden shelves with screws at each end of 2-square-wide grids.

Try this generator to make grids of the exact size you need. You can even customise the screw holes to the exact screws you have.

We’ll also use the Underware 2.0 cable management system, but in particular this is what we need to customize to make the diffusers. In particular, we’ll use This customiser since it’s compatible with openGrid and lets us generate whatever shape we need.

Both of these systems are great in their own right.

Customising Underware

After printing your grid and mounting it, open the underware generator. Click Customize and choose the basic shape to start with, eg a straight "I" piece. In the new browser tab click "Code" to open the OpenSCAD code that generates this model - you don’t need to know anything about programming or OpenSCAD. Scroll down until you see:

/*[Hidden]*/

Change it to

/*[Not Hidden]*/

And Press the "X" in the top right of the code view. Now the hidden settings are available to you.

Change the following settings, they’re in different sections.

Channel Total Height: 15
Channel Length Units: how long do you need the channel?
Suppress Connectors: NBNBNBN
topChamfer: 6
snapWallThickness: 1.2

About Suppress Connectors. Each channel will have connectors that grip into the grid. But they also get in the way of placing tiles that will hold your LED strip in place. I have chosen to make channels 7 units long with grips every other tile.

Generate the model then download it. The download window will ask you what kind of printer you have. Don’t worry if you don’t have a Bambulab printer, just click Confirm then Download. Sometimes the download button asks me if I’d prefer to download an STL file, I would, it’s printer agnostic. And sometimes it doesn’t. I don’t know why. If you download a .3mf file you can open it in your slicer anyway, you may have to switch printers and settings back to your own profiles. Or if you already have a project open in, for example OrcaSlicer, and load the file as a model, it may ask if you want to import Geometry Only, choose Yes.

Printing

I’m using Polymaker Polylite PLA Natural, I expect any "Natural" or even many "White" PLAs would work. A translucent filament is more transparent if printed hotter and slower, but I don’t want transparent, I want a more "frosted" look, so I didn’t bother slowing down print speed or anything like that.

But to go more towards a frosted look I am using a textured build plate and "fuzzy skin". But the fuzzy skin should be applied selectively so it’s not on the mechanical parts that grip into the grid.

Add a hight range modifier from 1.2mm to 11mm and apply the fuzzy skin setting to that.

I used a point distance of 0.2mm and a thickness of 0.1mm.

That’s it!

The right amount of poison

Tue, 13 Feb 2024 00:00:00 +1100

Oh, you don’t want any poison in your porridge. But how about in your computer’s memory?

Papa Bear - too much poison

Papa Bear likes his chair hard, his porridge hot and his browser written in a memory safe language that helps engineers avoid memory bugs like buffer overruns and use after frees.

But even Papa Bear has to compromise, part of Firefox is written in a memory safe language and the rest is written in C++. When using C++ there are a variety of defenses programmers can take to help catch memory errors. One of those is called memory poisoning.

mozjemalloc the memory allocator built into Firefox will poison memory by calling memset(aPtr, 0xE5, size); before freeing it. Any memory containing the pattern 0xE5E5E5E5 is therefore very likely to be memory that’s already been freed. This has two and a half benefits: If some code were to free and then dereference some memory (a use after free bug) it would most likely cause the browser to crash, which is much better than a potentially exploitable bug allowing Goldilocks to steal Papa Bear’s banking credentials! The other benefit is that when Firefox does crash due to such a use-after-free, the presence of this pattern in the crash report allows engineers to see the type of error that occurred and hopefully fix the mistake.

Note that back in March 2023 we moved the poison operation outside of the arena lock’s critical section; which improved performance in some tests.

Mama Bear - no poisoning

You probably figured out by now that I’m going to persist with this metaphor. Mama Bear likes her chair soft, her porridge cold (and congealed (yuck)), and her browser fast.

But how much faster is Mama Bear’s experience? This is the question that was raised recently when Randell Jesup was benchmarking various memory allocators in Firefox. He noted that while mozjemalloc performs poisoning, many of the other allocators do not and to compare the performance of the allocators more fairly they should either all perform poisoning or none of them should.

And so Randell noted that, depending on the test, Firefox could be between 0.5% and 4% faster with poisoning disabled.

There are some results I collected. The "sp2" (Speedometer 2) and "sp3" (Speedometer 3) tests are browser benchmarks - larger numbers indicate better performance. The amazon and instagram tests are pageload tests measured in seconds with the ContentfulSpeedIndex metric - smaller numbers indicate better performance.

	sp2 (score)	sp3 (score)	amazon (sec)	instagram (sec)
Poison	178.84 ± 0.84	13.32 ± 1.03	243.2 ± 1.96	419.43 ± 1.04
No poisoning	179.42 ± 0.48	13.39 ± 0.31	237.55 ± 2.6	414.5 ± 0.8

sp2 (score)

sp3 (score)

amazon (sec)

instagram (sec)

Poison

178.84 ± 0.84

13.32 ± 1.03

243.2 ± 1.96

419.43 ± 1.04

No poisoning

179.42 ± 0.48

13.39 ± 0.31

237.55 ± 2.6

414.5 ± 0.8

The speedometer figures are pretty close and these are the best pageload figures (the others showed very little difference but nothing regressed, yes I’m aware I’ve cherry-picked data).

This means that if it weren’t for the lack of security and debugability Mama Bear would have the right approach.

Baby Bear

Baby Bear loves a compromise, they want their computer to be safe from Goldilocks' hacking attempts but also love performance improvements.

One compromise may be to probabilistic poison memory some of the time, e.g. a roughly 5% chance of poisoning. That’s more complex and involves a memory write anyway to keep the "time until poison" counter updated. We didn’t investigate it. But it’s worth noting that it would be similar in spirit to the Probabilistic Heap Checker (PHC) that’s rolling out in Firefox or the similar GWP-ASan capability in Chrome.

Instead we tested "what if we poison only the first cache line of a memory cell". Andrew McCreight and Olli Pettay pointed out that Element, a common DOM structure, is 128 bytes long and poisoning it is useful to detect memory errors in DOM code, as a lot of DOM code will involve Element.

We tested poisoning the first 64, 128 and 256 bytes of each structure. We assume that management of cache and writing cache lines back to RAM is going to be the dominant cost. Therefore we round-up our writes to the next cache line boundary..

For example, on a computer with 64-byte cache lines, if a 96-byte object is allocated so that the first 32-bytes is in one cache-line, while the next 64-bytes is in another. Our 64-byte write would cover two halves of different cache lines. In this case we will poison all 96-bytes because doing so writes to the same number of cache lines as the original 64-byte write.

Let’s add these options to our table of results.

	sp2 (score)	sp3 (score)	amazon (sec)	instagram (sec)
Poison	178.84 ± 0.84	13.32 ± 1.03	243.20 ± 1.96	419.43 ± 1.04
Poison 256	179.50 ± 0.55	13.35 ± 0.33	240.47 ± 2.82	415.28 ± 1.30
Poison 128	179.19 ± 0.43	13.35 ± 0.59	241.62 ± 3.05	414.95 ± 1.15
Poison 64	179.09 ± 0.87	13.33 ± 0.83	242.13 ± 2.56	414.11 ± 0.91
No poisoning	179.42 ± 0.48	13.39 ± 0.31	237.55 ± 2.60	414.5 ± 0.8

sp2 (score)

sp3 (score)

amazon (sec)

instagram (sec)

Poison

178.84 ± 0.84

13.32 ± 1.03

243.20 ± 1.96

419.43 ± 1.04

Poison 256

179.50 ± 0.55

13.35 ± 0.33

240.47 ± 2.82

415.28 ± 1.30

Poison 128

179.19 ± 0.43

13.35 ± 0.59

241.62 ± 3.05

414.95 ± 1.15

Poison 64

179.09 ± 0.87

13.33 ± 0.83

242.13 ± 2.56

414.11 ± 0.91

No poisoning

179.42 ± 0.48

13.39 ± 0.31

237.55 ± 2.60

414.5 ± 0.8

As above, sp2 and sp3 are scores - bigger numbers are better. While amazon and instagram are page load tests where smaller numbers are better.

As expected the partial poisoning results fall between full and no poisoning. But what’s a little bit surprising is that in some tests (sp2 and amazon) poisoning a larger amount of memory made things faster. This could be because the memset() routine or the hardware itself is able to optimise larger writes more effectively. That said it’s important to acknowledge that the standard deviation is fairly high and doing the right statistical analysis is beyond this blog post.

Just right

Since poisoning more memory isn’t much slower and in some cases is faster than poisoning a little memory, then we might as well choose to poison 256 bytes which comfortably covers the Element object and most others and for the others it likely covers many of their most-often accessed fields. We’re confident that this is enough to help us catch many errors that can be caught with poisoning. While also performing well enough, especially for the pageload tests where it is closer to the performance available with poisoning disabled. We think that Baby Bear would agree, it is Just Right.

It gets better

With the Probablistic Heap Checker (PHC) rolling out soon we will have an even greater ability to catch information related to memory errors. I’ll be writing about this in the future.

Why Papa Bear is safe and Mama Bear is secure?

In some ways it feels more natural to lean in to (negative) gender stereotypes where Papa Bear wants things fast and Mama Bear is the cautious one. I considered this however to make comprehension easier it’s easier to explain poisoning before explaining turning poisoning off and the nursery tale describes Papa Bear’s preferences first, so that’s the order I introduced them here. Flipping the script on gender stereotypes was accidental.

Waiting for web content to do something in a Firefox mochitest

Fri, 25 Nov 2022 00:00:00 +1100

It’s not unusual for a Firefox test to have to wait for various things such as a tab loading. But recently I needed to write a test that loaded a content tab with a web worker and wait for that before observing the result in a different tab. I am writing this for my own reference in the future, and if it helps someone else, that’s extra good. But I don’t think it will be of much interest if you don’t work on Firefox as the problem I’m solving won’t be relevant and the APIs won’t be familiar.

I don’t think of myself as a JavaScript programmer - I’m learning what I need to know when I need to know it, but mainly to write tests. So I’m not sure I’ll pitch this article at any particular level of JS knowledge, sorry.

Web Workers

Web Workers provide web pages a way to execute long-running JavaScript tasks in a separate thread, where it won’t block the main event loop. They solve the same problem, allowing a page to use concurrency. However their programming model is more like processes because they don’t share state (global variables or even functions) and communicate by sending and receiving messages.

I realise this is a tangent but it’s a topic I like and you may have the same questions I did: So if workers are supposed to solve the same problems as threads do in other languages, why are they more like processes? Furthermore, at least in Firefox, each worker instantiates another copy of the JavaScript engine (the JSRuntime class) with its own instantiation of JIT, GC etc. Isn’t this fairly heavy just to add concurrency?

It is, but there are benefits:

I’m not certain, but I think this was the easiest way to retrofit concurrency to JavaScript (the language standard) without breaking backwards compatibility with existing web sites.
Message-passing concurrency makes the boundary between threads very clear. This makes it a simpler programming model, especially if you’re working on some code that is isolated from the concurrency happening elsewhere.
It worked for Erlang, although Erlang likely shares bytecode caches and some other systems. But not garbage collection.

Anyway, the point is that Web Workers are concurrent "process like" things that communicate through message-passing.

about:performance

Firefox has a number of about: pages, used for diagnostics and tweaking. about:config is probably the most infamous (if you touch those settings you can break your browser or make it insecure). about:support is interesting too it contains diagnostic information about Firefox on your computer.

Today we’re looking at about:performance, which is useful when you are thinking "Firefox seems slow, I wonder why..". about:performance will show your busiest tabs, how much CPU time/power and memory they’re using.

Measuring memory usage can be tricky at the best of times (more on this in an upcoming article). We can’t afford to count every allocation since that is too slow for a page like about:performance. Although about:memory comes closer to doing this. For about:performance we can ask major subsystems how much memory they’re using and rely on their counters. This isn’t accurate but it’s good enough.

I noticed two major things that weren’t counted:

Malloc memory used by JS objects was not counted.
Web workers were not counted.

I fixed them in Bug 1760920.

So I wanted to write a test that would verify that we are indeed counting memory belonging to web workers.

My web worker

To make it easier to see if we’re counting a component’s memory, it’s great of our test causes that component to use a lot of memory then we can test for that.

Here’s a Web Worker that uses about 40MB of memory using an array with 4 million elements.

var big_array = [];
var n = 0;

onmessage = function(e) {
  var sum = 0;
  if (n == 0) {
    for (let i = 0; i < 4 * 1024 * 1024; i++) {
      big_array[i] = i * i;
    }
  } else {
    for (let i = 0; i < 4 * 1024 * 1024; i++) {
      sum += big_array[i];
      big_array[i] += 1;
    }
  }
  self.postMessage(`Iter: ${n}, sum: ${sum}`);
  n++;
};

It registers an onmessage event hander. When the page sends it a message it will execute the anonymous function. The first time this happens the function will create the array, the next time it will manipulate the array. Since the array is a global and is also captured by the handler I doubt the GC would free it. But I also don’t want an optimiser (now or in the future) from reducing the whole program to a large summation, or caching an answer. Which is why the array is manipulated each time the event handler is called. It doesn’t matter that it’s ridiculous - it’s a test - just that it uses "enough" memory.

From the main page it can be started like this:

  var worker = new Worker("workers_memory_script.js");
  worker.postMessage(n);

But that’s not enough to make a working test.

The test

Our test needs to open this page in one tab, and in another tab look at about:performance and observe that the memory is being used. Opening and managing multiple tabs and is standard faire for a browser test, but what we need is for our test to wait for the tab with the worker to be /ready/.

Waiting for a tab to be loaded is also very easy, which means that the tab will have executed worker.postMessage(n) by the time the test code checks. But that doesn’t mean that the worker has received the message.

So we need to make our test wait for the worker to start and complete one iteration (creating its array).

In the test we can add code such as:

  let tabContent = BrowserTestUtils.addTab(gBrowser, url);

  // Wait for the browser to load the tab.
  await BrowserTestUtils.browserLoaded(tabContent.linkedBrowser);

  // For some of these tests we have to wait for the test to consume some
  // computation or memory.
  await SpecialPowers.spawn(tabContent.linkedBrowser, [], async () => {
    await content.wrappedJSObject.waitForTestReady();
  });

The last three lines here are the interesting ones. SpecialPowers.spawn allows us to execute code in the context of the tab. In which we wait on a promise that the test is ready.

Now we need to add this promise to the page that owns the worker:

  var result = document.querySelector('#result');
  var worker = new Worker("workers_memory_script.js");
  var n = 1;

  var waitPromise = new Promise(ready => {
    worker.onmessage = function(event) {
      result.textContent = event.data;
      ready();

      // We seem to need to keep the worker doing something to keep the
      // memory usage up.
      setTimeout(() => {
        n++;
        worker.postMessage(n);
      }, 1000);
    };
  });

  worker.postMessage(n);

  window.waitForTestReady = async () => {
    await waitPromise;
  };

Starting at the bottom. For some reason I had to wrap the promise up in a function, I can’t remember why! I’m tempted to complain about JavaScript and it’s inconsistent rules here, but it could also be my limited understanding preventing me from getting it. What I do know is that this function must be in the window object so that the test code above can find it in wrappedJSObject.

The promise wrapped here (waitPromise I could have picked a better name) is resolved when ready() is called, which happens after we receive the worker’s response. Finally we use setTimeout() to post another message to keep memory usage up. I don’t know why this was necessary either. Was the worker completely terminated without it?

One more thing

Our test almost works. For whatever reason when the test accesses the right part of the about:performance page there’s no value for how much memory is being used. Waiting for a single update fixes this:

  if (!memCell.innerText) {
    info("There's no text yet, wait for an update");
    await new Promise(resolve => {
      let observer = new row.ownerDocument.ownerGlobal.MutationObserver(() => {
        observer.disconnect();
        resolve();
      });
      observer.observe(memCell, { childList: true });
    });
  }
  let text = memCell.innerText;

For the complete code for this test checkout Bug 1760920 and toolkit/components/aboutperformance/tests/browser.

There’s things I don’t know

There’s three places here where I’ve said "it needs this code, I don’t know why". I hate programming like this, and I feel shameful writing it in a blog post and calling myself an engineer. I don’t want to spin it as a joke on JavaScript, or myself "lol, that’s programming! AMIRITE?!" There’s obviously some further subtleties I don’t know the rules for, and JavaScript does have some pretty inconsistent rules, throw in a browser, two tabs and a web worker and feeling like you don’t know how something works is relatable.

Do I wish I knew? Sure, I’m uncomfortable not knowing, but I’ve already spent enough time on this. But this is also why I wrote down what I do know. Next time I’ll be able to find this much and solve my problem quicker.

Running the AWSY benchmark in the Firefox profiler

Sat, 18 Sep 2021 00:00:00 +1000

The are we slim yet (AWSY) benchmark measures memory usage. Recently when I made a simple change to firefox and expected it might save a bit of memory, it actually increased memory usage on the AWSY benchmark.

We have lots of tools to hunt down memory usage problems. But to see an almost "log" of when garbage collection and cycle collection occurs, the Firefox profiler is amazing.

I wanted to profile the AWSY benchmark to try and understand what was happening with GC scheduling. But it didn’t work out-of-the-box. This is one of those blog posts that I’m writing down so next time this happens, to me or anyone else, although I am selfish. And I websearch for "AWSY and Firefox Profiler" I want this to be the number 1 result and help me (or someone else) out.

The normal instructions

First you need a build with profiling enabled. Put this in your mozconfig

ac_add_options --enable-debug
ac_add_options --enable-debug-symbols
ac_add_options --enable-optimize
ac_add_options --enable-profiling

The instructions to get the profiler to run came from Ted Campbell. Thanks Ted.

Ted’s instructions disabled stack sampling, we didn’t care about that since the data we need comes from profile markers. I can also run a reduced awsy test because 10 entries is enough to create the problem.

export MOZ_PROFILER_STARTUP=1
export MOZ_PROFILER_SHUTDOWN=awsy-profile.json
export MOZ_PROFILER_STARTUP_FEATURES="nostacksampling"
./mach awsy-test --tp6 --headless --iterations 1 --entities 10

But it crashes due to Bug 1710408.

So I can’t use nostacksampling, which would have been nice to save some memory/disk space, never mind.

So I removed that option, then I get profiles that are too short. The profiler records into a circular buffer so if that buffer is too small it’ll discard the earlier information. In this case I want the earlier information because I think something at the beginning is the problem. So I need to add this to get a bigger buffer. The default is 4 million entries (32MB).

export MOZ_PROFILER_STARTUP_ENTRIES=$((200*1024*1024))

But now the profiles are too big and Firefox shutdown times out (over 70 seconds) so the marionette test driver kills Firefox before it can write out the profile.

The solution

So we hack testing/marionette/client/marionette_driver/marionette.py to replace shutdown_timeout with 300 in some places. Setting DEFAULT_SHUTDOWN_TIMEOUT and also self.shutdown_timeout to 300 will do. There’s probably a way to pass a parameter, but I didn’t find it yet. So after making that change and running ./mach build the invocation is now:

export MOZ_PROFILER_STARTUP=1
export MOZ_PROFILER_SHUTDOWN=awsy-profile.json
export MOZ_PROFILER_STARTUP_FEATURES=""
export MOZ_PROFILER_STARTUP_ENTRIES=$((200*1024*1024))
./mach awsy-test --tp6 --headless --iterations 1 --entities 10

And it writes a awsy-profile.json into the root directory of the project).

Hurray!

Follow-up

Whimboo says that setting toolkit.asyncshutdown.crash_timeout might help. But it may wait until after some stuff has been implemented:

a solution here should also be to extend the toolkit.asyncshutdown.crash_timeout value

oh wait. actually we haven’t fixed that yet, but only use it via geckodriver`

— Whimboo

Project MemShrink

Fri, 25 Sep 2020 00:00:00 +1000

I asked, and have been given a new project at work. Together with another engineer I will be working on reducing Firefox’s memory footprint.

Mozilla has run a MemShrink project in the past, which even though it has wound-down, Firefox is still regarded as being more memory efficient than Chrome and the other chromium-based browsers. However keeping this accolade is going to be difficult.

Lately we’re working towards project fission - a site isolation feature and new process model for Firefox. This will necessarily require more OS processes for Firefox (particularly for users who browse multiple different sites in many tabs) which requires more memory.

We’ve started a new memory reduction project to ensure we can enable Fission without excessive memory use: Fission MemShrink. This was actually started in 2018, but now we have two full time engineers on it and one of them is me.

So far

A lot of the "easy wins" have already been won: we reduced the base memory usage on Windows from 21.5MB in 2018 to 14.8MB in 2019, and now 11.5MB in September 2020. This included situations where memory was used excessively, or not released when it could be, and other low-hanging-fruit. However that’s just base memory, the memory used by a content process before it loads a page. Memory usage of the whole browser has increased over the past year (by about 10% as best I can tell from our tracking).

Where to optimise

(TL;DR: use a profiler.)

The main goal is to reduce the overhead from enabling fission. There’s multiple places to look:

Reduce the number / size of structures that are used more commonly with fission.
Reduce the amount of memory an "empty" Firefox content process consumes (that’s the base memory above).
Reduce the overall memory usage of the browser - that’s always a good thing!

I’ve picked the 2nd, or almost-2nd one: Reduce the amount of memory overhead for a process loading a tiny page (or iframe). Firefox can generate a memory report, showing where memory is allocated.

With fission enabled I load http://example.com in one tab (because it’s a small page), and open about:memory in another tab, click "Measure" and Firefox will generate a memory report. We’re using this as the starting point for where to concentrate our optimisation efforts.

jemalloc

Table 1. jemalloc size classes
Category	Subcategory	Size
Small	Tiny	4
	Tiny	8
	Quantum-spaced	16
		32
		48
		…
		480
		496
		512
	Sub-page	1 kB
	Sub-page	2 kB
Large		4 kB
		8 kB
		12 kB
		…
		1012 kB
		1016 kB
		1020 kB
Huge		1 MB
		2 MB
		3 MB
		…

For a small process we noted that the memory allocator has more overhead than we’d like, >1.90MiB out of a 20.7MiB process (9.21%) and it may be worth-while looking here as place to reduce overheads. This overhead is the bin-unused item on these memory reports. So this is where I’m starting.

Firefox uses a fork of the jemalloc memory allocator, which has now been heavily modified. jemalloc allocates memory in several size classes, the most popular comment in the mozjemalloc.cpp file contains a table explaining its size classes (Table 1):

Note that these sizes can vary with different settings, this is the default on a 32bit build with 4KB pages. On a 64bit build the 4-byte class is missing and windows is always missing the word-sized class.

The 'bin-unused' item on the memory reports is only relevant for the small size classes in this table. In these size classes an area of memory that jemalloc calls a run (one or more pages) is divided up into allocations of this size class, So a request for 12 bytes is rounded up to 16 and allocated in a run that contain other 16 byte allocations. 'bin-unused' measures all the unallocated slots in these runs.

This is not wasted memory or lost memory. But it’s not "merely unused" either. For example, there may be many unused 16-byte slots, even some close together, but they cannot be used to satisfy a request for 32 bytes. And because they’re less than 4KB, they represent physical memory - they cannot be paged out without paging out the rest of that memory page.

Note	I think I owe you an article on what a memory page is. Since I haven’t defined that and have used it fairly liberally. If you don’t know then just pretend I’m saying "4KiB area" and await a future article!

Note	A `run` may be one or more pages. Packing 2KB annotations, one per page would be inefficient so when allocations are larger (or don’t align well with their header) jemalloc will use longer runs of pages. Here is a table with examples of run lengths.

(or sometimes more, but for this article I’ll assume a page) will only store items of that specific size class. This reduces overheads since the size information and if this were a GC other metadata) could be shared between all the items in the same page.

Wish me luck

I could go on with what I’ve found, and I will but in future posts. By keeping this post shorter I can publish it today. Generally this may help me write more generally, if each post is less time-consuming. So forgive me for leaving you in suspense, but that’s what’s best to maintain a blog at all.

In the next post I’ll write more about bin-unused and something called slop and describe what I might be able to do / have done to fix them. I’ll also write an introductory post about paging.

Thanks for reading.

Case Sensitivity In Grammars

Wed, 20 May 2020 00:00:00 +1000

A recent change to Plasma caused me to think choices that various languages make with regard to case in their grammar. I originally assumed there are just two choices in certain grammars, Case sensitivity or sigils. But there are some other options and I’ll share them here.

Parsing

Computer languages are compiled or interpreted in a number of stages. The first four stages are:

Tokenisation (aka lexical analysis)
Parsing (aka syntactic analysis)
Symbol resolution
Semantic analysis

Often some of these stages are combined, many languages historically did symbol resolution during parsing, and some do tokenisation and parsing at the same time.

This article is concerned with parsing: taking a list of tokens and generating an abstract syntax tree. The parser must figure out what each token’s role is. For example in a C program does the '*' symbol represent multiplication, or pointer-dereference, figuring that out is the parser’s job.

One important consideration is that information should not flow backwards from later stages to earlier ones. This means that the parser should not need information from semantic analysis to make such decisions. It should be possible to decide from the token stream and grammar alone.

If you’re wondering why I’ve emphasised "should" and are thinking "but this just seems sensible, surely all languages do this?" there are popular languages that definitely break this guideline. One example is C++, which needs to lookup the meaning of symbols to figure out if a < symbol is a less than token or the beginning of a template variable list. So if C++ can do it why is it so bad?

It makes compilers more complex, usually this is handled by performing more than one compilation stage at a time, and that means both making the implementation more complex and requiring other changes to the language. In C and C++ declarations must be parsed and have some types of semantic analysis performed before uses of those declarations can be parsed. That means that the declaration must occur before the use in the source file, and even in header files. Which is why the order that header files are included matters. All this makes the language more difficult for programmers to use, that’s something we want to avoid with Plasma.

Additionally, by making the tools more complex it makes it harder to make new tools like documentation generators, linters and autoformatters. They may need to run more compilation stages to achieve their job when languages break this guideline.

Ambiguity

In Plasma the ambiguity we’re concerned about is that in some cases identifiers could refer to either a type or a type variable - syntactically different concepts we’d like to distinguish during parsing. The above guideline says that we have to be able to make this distinction without looking at anything but the parsing context and the identifier itself.

Note	Identifiers are the names of variables, functions, types and other symbols appearing in a language - they’re not keywords such as "return" or "if", or other symbols.

Languages with case sensitivity

Languages such as Haskell, Prolog and Mercury are case sensitive, they use case to distinguish the role of some symbols from others:

Haskell: Types begin with an uppercase letter while type variables begin with a lower case letter:

-- Haskell allows the [ ] syntax in type declarations,
-- but we use the word 'List' for our example.
length :: List a -> Integer

Prolog & Mercury: Atoms, predicates and functors begin with lower case letters and variable begin with upper case.

length([], 0).
length([X | Xs], N+1) :-
   length(Xs, N).

Mercury also distinguishes types from type variables like Haskell, but with upper and lower case reversed.

:- pred length(list(T)::in, int::out) is det.

There are other examples of languages with case sensitivity in their syntax, such as Java, but I don’t know if they’d be ambiguous without it.

Prolog is a particularly strong case where an ambiguity could be a problem. In Prolog both atoms and variables are created just by using them once. Mixing them would make Prolog even more permissive than it already is.

Languages with sigils

OCaml resolves the same ambiguity between types and type variables that both Haskell and Mercury have, but it does so using sigils (') for type variables:

val length : 'a list -> int

We’ve made the same change to Plasma, and used the same symbol. This was made to support programming in scripts without case, however I hope that while people program in a language with the roman script (e.g: English) we will use case as a matter of style:

// Plasma will allow the [ ] syntax in the type signature in the future
func length(list : List('x)) -> Int {
   match (list) {
      [] ->               { return 0 }
      [var x | var xs] -> { return 1 + length(xs) }
   }
}

Note also that we have changed the pattern matching syntax to also use the var keyword to introduce new variables. This functions a lot like the sigil in type expressions to disambiguate data constructors from new variables. It has the interesting property that it is now used in two out of three places where a new variable is introduced (the remaining one is parameter lists).

Live with ambiguity?

Of course, one option is to just live with ambiguity. Let’s look at a type declaration.

type List(x) = Nil
             | Cons { x, List(x) }

There’s actually nothing ambiguous here at all! Each identifier here is introduced in the same declaration. Nil and Cons are their own declarations, and the other two identifiers List and x are declared on the left-hand-side of = then used on the right. When they occur on the right we’ve already parsed their declaration on the left. This means, depending on how you look at it, the grammar is either context sensitive or we’ve broken the guideline above that parsing must not depend on later stages. Let’s call it a "weak" case of breaking the above guideline, because it’s within the same declaration we can allow it.

Even if other symbols appeared on the right-hand-side of = their role (in valid programs) would be unambiguous. They’d have to be names of types because all variables must be introduced on the left.

However a type expression when it appears inside a function declaration is ambiguous:

func length(list : List(x)) -> Int

Here x may be a type name or a type variable. We may resolve the ambiguity by checking if a type named x already exists, and if it does assume this is a name. This could be resolved after parsing, preserving our guideline above which would allow us to define the type x after using it.

Depending on the type system List may also be ambiguous, e.g: it could be a type variable of kind * → * or the name of a type. However if the language has only kind * then we know it must be a type’s name, because only type names can take parameters. Depending on what languages you’ve used before, this may have made no sense, if that’s the case I’ll just say it’s an important detail in Haskell because monads use the kind * → *.

How about that other case we had in Plasma, of pattern matching?

   match (list) {
      [] ->       { return 0 }
      [x | xs] -> { return 1 + length(xs) }
   }

Again we could lookup x and xs in a symbol table and find out if they’re data constructors, and if that fails we can assume they’re type names.

While this is possible, and means sense for valid programs, but ambiguity becomes a pain in the neck when a program is not what the programmer intends to write. I’ve not said invalid programs because it’s possible that many of these programs would be accepted by the compiler but then be buggy.

type MyTypeA
type MyList = List(MyTypeB)

There’s a spelling error here. The programmer has written MyTypeB instead of MyTypeA. Either way the compiler may accept this program but now MyList has a different meaning. Arguably that’s no worse than if there were two types with names with similar spellings, but that’s a code smell programmers may wish to avoid because it leads to the same type of confusion.

Likewise, let’s say a programmer writes:

func length(list : List(x)) -> Int

And they expect x to be a type variable, and use it as such:

var a = length([1, 2, 3])
var b = length(['a', 'b', 'c'])

That’s fine until elsewhere in the same module they add a type called 'x'! Now they have compilation errors where they expect to use their generic list. But of course their length function where the identifier list occurred won’t be where the compilation error is reported, it may even be reported in a separate module if length is exported but not used in this module. They’re going to be very annoyed with the language designer! This may also work fine until some time six months from now they add the type x!

I generally want to avoid this kind of ambiguity while designing Plasma. Plus it breaks one of my design philosophies for Plasma and that is a thing should look like what it is. That’s another way to say the language should be unambiguous, or even that the grammar should be context free (but I’m not making that a hard rule, there’ll be times when I break it).

I also considered allowing partial ambiguity. That is using case to hint to the compiler the role an identifier plays, and if it doesn’t make sense then the compiler can re-evaluate the meaning. This ends up being very similar to a complete ambiguity that it’s not worth much discussion.

Languages that declare type parameters

There’s one other way to avoid ambiguity. And we saw it above:

type List(x) = Nil
             | Cons { x, List(x) }

Here all the identifiers are introduced in such a way as they’re unambiguous. There’s other languages that do this with type variables appearing in function declarations and definitions, e.g: C++.

template<typename T>
int length(List<T> list);

The template keyword introduces a parameter list of type variables. We could do that in Plasma:

generic(x)
func length(list : List(x)) -> Int {
   match (list) {
      [] ->         { return 0 }
      var x, xs:
      [x | xs] ->   { return 1 + length(xs) }
   }
}

Note that we also did the same to introduce x and xs as variables before they occurred in the pattern.

Java doesn’t have the template keyword like C++, instead its grammar allows it to use use < > brackets to give the parameter list. I assume that C++ can’t do this because it’d be ambiguous. In Plasma that could look like:

func length<x>(list : List(x)) -> Int

That’s not terrible, and would certainly solve the ambiguity with type variables. I personally have a gut-reaction against this because it reminds me of C++ and gnarly template errors, but I realise as I’m writing this, I wouldn’t rule it out because it could also make it easier to add constraints (such as interfaces) on these type variables in a way that fits the syntax:

func sort<x : Ord>(list : List(x)) -> List(x)

We can’t reasonably extend this concept to the pattern match, there the functor (in the syntactical sense) is the → and I wouldn’t want to add parameters to that.

We can however use this idea to remove Haskell’s case sensitive grammar without introducing sigils, with a slight modification to the typeclass constraint syntax:

list :: a => [a] -> Int

Wrapping up

There’s more than just the two choices I had initially assumed. I’ve found five:

Case sensitive grammar
Sigils
Ambiguity
Declare new type variables with a keyword (C++)
Declare new type variables with a parameter list (Java)

And I’m surprised to find that although I’ve made the decision to use sigils, I’m also drawn to the parameter list idea such as Java uses. Plasma is far from 1.0, and for now I reserve the right to change these decisions as necessary and may revisit this decision in the future. For now I will at the very least sleep on it.

Reorg’d

Mon, 17 Feb 2020 00:00:00 +1100

You may have heard recent news of the changes happening at Mozilla where I work. As part of those changes we’ve also re-organised (reorg’d) many teams and individuals.

My team assignment has changed and I no-longer work on SpiderMonkey’s garbage collector. This is a bit of a bummer because I was hoping to make memory management and garbage collection my career focus and become an expert, like I had already done with automatic parallelism.

My new team is the Fission team, a new team to work in stronger process isolation for Firefox. So far I’ve been working on DocumentChannel with several other engineers. DocumentChannel is a feature/project for launching new page/iframe loads from the parent process so that redirects to not spawn two many short-lived processes. This feature has landed in Firefox Nightly but there’s still refinements to make. So far I’m enjoying working with another team and getting to know more people within the organisation.

When we roll-out Fission it’s going to add new challenges for Firefox’s memory usage. I’ll be putting myself forward at that time to work on reducing memory usage (or making smarter choices with memory), with any luck that will mean working on memory allocators or the GC again.

Cpu Cache

Wed, 01 May 2019 00:00:00 +1000

Whenever discussing CPU-bound performance (at least in the last 10-15 years) CPU cache is almost always a dominant factor. However often people say "oh probably cache" when explaining away some observation. They’re probably right, but let’s dive a little deeper into how exactly a modern CPU cache (or caches) works.

We’re going to learn how to unpack jargon such as:

Level 1 32KB i-cache and 32KB d-cache, 8-way set associative,
Shared level 3 8MB cache.

And also talk about cache behaviour in multi-processor systems as well as another type of cache called a TLB.

I’m working on a set of articles that are going to deal with cache effects, and wanted to start with this background information, not all of it will be needed but all of it is interesting (or tedious, depends on how tightly wound your propeller-hat is).

I’m going to assume you already know that cache is a type of fast memory that is "nearer" to the processor and so communication with it is faster with lower latency. That it holds copies of some things from regular memory to speed up program execution, because programs will tend to access memory near memory they’ve already accessed recently.

While I write this I was checking my knowledge with some web searching. I found that there are plenty of other resources online including worked examples. But I thought I’d summarise it anyway.

Cache levels

I remember owning a 486 motherboard that had an extra slot, next to the CPU that someone told me was for "cache". I found a circuit board that fitted there but I never tested to see if it made a difference. Point is that when the slot was empty, or if your 486 motherboard didn’t have it, it had 0 levels of cache. When you put the right card in that slot, then you had "one level of cache".

Edit 2019-05-03

I mis-remembered, and just started reading the Game Design Black Book: Doom (which looks great! so excited!): The 486 has an integrated L1 cache and the slots/sockets available on motherboards are for L2.

My i7 Desktop has 3 levels of cache. The neat hwloc-ls tool on Linux will show you something like:

Memory hierarchy

Package L#0 + L3 L#0 (8192KB)
  L2 L#0 (256KB) + L1d L#0 (32KB) + L1i L#0 (32KB) + Core L#0
    PU L#0 (P#0)
    PU L#1 (P#4)
  L2 L#1 (256KB) + L1d L#1 (32KB) + L1i L#1 (32KB) + Core L#1
    PU L#2 (P#1)
    PU L#3 (P#5)
  L2 L#2 (256KB) + L1d L#2 (32KB) + L1i L#2 (32KB) + Core L#2
    PU L#4 (P#2)
    PU L#5 (P#6)
  L2 L#3 (256KB) + L1d L#3 (32KB) + L1i L#3 (32KB) + Core L#3
    PU L#6 (P#3)
    PU L#7 (P#7)

I have four cores, two processing units (PU) in each, and three levels of cache. Each core has three types of cache: L1d (level 1 data), L1i (level 1 instruction), both 32KB large, and a 256KB L2 (instructions and data). The package (that’s what you’re holding when you’re installing a CPU) itself has another level of cache (L3) shared between all four cores.

Cache is expensive memory, and the faster you need it the more expensive it is. It’s common to arrange it in levels, with the most expensive fastest cache memory nearest (or inside) the core. That’s our L1i and L1d. Because it’s expensive there’s only 64KB of it per core. We can afford 8MB of the least expensive cache (but still expensive relative to main memory).

Since this is a multi-processor we notice that if there’s only a single thread running it can use only its cores' 64KB and 256KB of L1 and L2. But it can use the whole 8MB of L3. When tasks run on other threads they share this 8MB (with whatever policy the CPU chooses). if some threads access the same data, they benefit by communicating through this shared last-level cache. There’s another term you may encounter: last-level cache (LLC) it’s whatever cache is furthest from the processor.

The other thing going on here is that the L1 is split between instructions (code) and data. There’s probably a good reason for that, it may be because code and data are typically fetched through different pathways and that code is almost always read-only. But those are just my guesses.

Cache lines

Cache is arranged in lines. Let’s see ask /proc/cpuinfo:

clflush size    : 64
cache_alignment : 64

That’s not exactly the answer for the question I was asking, but it’s close enough for jazz. Also I happen to know based on other sources. This CPU has 64-byte cache lines.

In other words, the cache manages 64-byte long (and aligned) blocks, or lines of memory. Managing cache in lines improves its use, since if you read the first word from a line, you’re likely to read following ones and now they’re hot in your cache (words are 8 bytes (64-bits) long on a 64bit system). Larger cache lines reduce bookkeeping costs since the CPU will keep data per-line. However large lines will also reduce how well the cache can handle random access workloads.

Cache associativity

When a CPU wishes to retrieve some memory it asks the cache; if the cache is 8MB and contains lines of 64 bytes each, then the CPU needs to know which of the 131,072 cache lines to check.

The simplest method uses the low-order bits of the address shifted right so that the bits that address the byte within the cache line aren’t used. For an 8MB cache with 131,072 64-byte lines that’s:

Example

line = (address >> 6) & 0x1FFFF

Then the CPU compares that line’s address to the address for the memory request. This means that the cache must store the addresses for each cache line, but in case of my i7 it can skip the 6 lowest bits since that’s how it’s aligned. And also skip the 29 highest bits, because my i7 has only a 39-bit physical address space despite a 48-bit virtual address space and 64-bit general purpose registers. Leaving only 30 bits of the cache line’s address that need to be stored, less than half!

Anyway, if that matches then the cache lookup is a hit and the cache elides (FIRST TIME I used that word) the memory access. If it doesn’t match then the lookup is a miss.

In this scheme every physical address maps to exactly one cache line. To improve the cache’s hit rate we can increase this.

Now we change the equation above to calculate the "set", we also take a bit of precision away - there are half as many sets as there are cache lines.

Example

set = (address >> 6) & 0xFFFF

Each set in this example has two cache lines in it, the memory we’re looking up can be cached in either; the cache system will check both. This is a 2-way set associative cache. My i7 has a 16-way level 3 cache (the cpuid program on Linux will tell you).

This improves the hit rate, because if two addresses would have been stored in the same cache line, and accessing one may have evicted the other, even if it was recently used and going to be used again. However with an associative cache these collisions don’t lead to evictions as often. The CPU will use an "eviction policy" to decide which line within a set will be evicted.

It’s also possible to have a fully-associative cache, where any memory address can be stored in any cache line.

Inclusive or exclusive cache

If some data is present in the level 2 cache then is it required/expected to be present in L3?

Yes: the L3 cache is inclusive
No: the L3 cache is not inclusive

Edit 2019-05-02

Harold reminded me about Victim Caches, which is related to inclusive/exclusive. L2 is a victim cache if when something is evicted from L1 it is then stored in L2. Lines arn’t usually stored in L2 due to misses there.

Write-back vs write-through

When some data is written to that address, and it is cached, will it be written out to to memory/the next cache level immediately?

Yes: Write-through
No: Write-back

I’ve never knowingly seen a write-through CPU cache, I’ve usually heard this term for disk caches. But there’s a chance I’m wrong and write-through is useful for CPU caches for memory regions that map hardware.

Edit 2019-05-02

Mike remembers seeing configuration for write-through/write-back in a recent system’s BIOS. I have vague memories of this from a long time ago, memories I didn’t trust to be accuruate enough to report. Maybe it’s true, or maybe we both saw an option for disk cache.

Multiprocessor behaviour

Here’s where things get complicated. Let’s forget my i7, or at least forget the L1 and L3 from my i7.

Processor A reads memory location 5 into its cache (let’s assume it initially contains the value 3), modifies it and the result (4) is stored in Processor A’s write-back cache.

// ptr points to memory location 5,
int *ptr = 5;
// read and update
*ptr = *ptr + 1;

Now processor B wants to read the same memory location:

// ptr points to memory location 5,
int *ptr = 5;
printf("The number is %d\n", *ptr);

Does B see the number 3, or the number 4. We’re assuming that B runs after A. But even so there’s a good chance B will report "3". That’s because the "4" is in A’s cache.

To solve this we need some system of cache coherence which is almost always combined with some atomic operations and/or fences so that the processors can opt-in to ensuring that things are coherent. They don’t do it all the time because that would be slower / take more energy.

If A uses atomic instructions to read and update memory location 5. When B reads it, then depending on what kind of cache-coherence protocol is used either:

The correct value (4) can be read from main memory because A flushed it there and invalidated anyone else’s copy. So B knows it must read it from main memory.
The correct value might or might not be in main memory, but B knows that A has a valid copy.
B already knows the correct value, because it saw it go by on the memory bus when A wrote it, so it stored it in its own cache then (snooping).

There are more variations, and the 3rd option isn’t the only option for snooping. For example snooping might have noticed that A updated the value but B recorded only that its own value (if it had one) is invalid, and didn’t record the new one. Or only records values that look "interesting" according to some heuristic.

This is a very brief overview. What I really want to share here is that cache coherency is a thing that exists. It’s also one of the reasons why it’s difficult to scale up CPUs to many dozens of cores: the access to memory and coherency is a place where they must coordinate. Alternatives do exist, including NUMA (systems where each processor or small group of processors has its own memory) which may communicate between memories via other (often slower) means.

Memory barriers/fences

Above we introduced atomic instructions, these work well when operating on a single memory location. When more than one location is involved fences are often required. Let’s imagine we have a buffer that two processors use to communicate, this buffer might be used by something like a channel in the Go language.

// Write a value into the buffer
buffer[pos] = new_value;
pos++;

The write into the buffer and the write to the current buffer position are likely to both be cached. But what if the update to the position (pos) is flushed or evicted from the processors cache before the change to the buffer itself? Then another processor reading the buffer might read an invalid or incomplete item. What we need is a memory barrier (aka memory fence)

// Write a value into the buffer
buffer[pos] = new_value;
sfence();
pos++;

This store fence (an x86 instruction) tells the CPU that all the stores must be visible to other processors before any of the stores that follow. It ensures that the buffer’s contents are ready before the position is updated.

Provided there’s only one thread allowed to update pos then this code is now thread-safe.

There are also other types of fences and atomic instructions, providing various levels of strength. Each architecture is different.

When two unrelated things are used by different processors but stored in the same cache line this can lead to a lot of thrashing as the cache system tries to keep a coherent view of this busy cache line. This is known as false sharing. Normally unrelated things end up on different cache lines, but that’s not always true and sometimes they do appear on the same cache line. If that happens try to add padding or otherwise arrange for them to be allocated separately.

Other cache types

CPUs have other things that are either types of cache or things that just "use" cache.

μOP cache

Some more recent Intel CPUs use a μOP cache (micro-operation cache). This is like the L1 instruction cache and stores pre-decoded instructions. It’s good for accelerating short loops and avoids the need to re-decode instructions in these loops (but the loops have to be sufficiently short).

Page translation and TLBs

Translate look-aside buffers (TLBs) may be even more significant than cache. Memory addresses used by your program are known as virtual addresses. These must be translated into physical addresses before they can be retrieved, which is known as page address translation, or just translation.

32-bit Paging on x86 (From Intel manual)

The operating system is responsible for maintaining page tables (structures in memory) that tell the CPU what the physical address for a given virtual address is. In the figure these are shown as the page directory and page table. However since these tables are stored in memory to look them up requires memory accesses (two in the example shown). This could be quite painful, so the CPU will cache the results of these lookups in a special case known as a translate look aside buffer (TLB).

Here’s what my i7 says about its L2 TLB (it also has L1 TLBs but they’re more complex.

0xc1: L2 TLB: 4K/2M pages, 8-way, 1024 entries

Page translation is based around memory pages. Like cache lines, pages break the memory into pieces that get handled in a similar way. x86 pages are normally 4KB, more recent CPUs can support larger pages (we’ll see why in a moment). My L2 TLB for 4K or 2M pages stores 1024 entries and is 8-way associative.

With 1024 entries for typical 4K pages, this can cache page lookups for 4MB of memory. With 2MB pages this increases to 8GB. However I think operating systems and possibly even the CPU tend to prefer 4K pages.

My CPU also supports 4MB and 1GB pages, the former has a TLB at L1 for data only and the latter at L1 for instructions only.

Branch predictor

A modern CPU does its work in a pipeline. While some instructions are being executed or having their results stored, others will be being fetched and decoded. Keeping this pipeline full keeps performance up. One thing that can cause the pipeline to stall is conditional or indirect branch instructions.

In the case of conditional instructions usually some computation is needed to determine whether the branch will be taken. This computation will still be in progress at the time the CPU will want to start fetching instructions and keeping the pipeline full. The CPU will make a guess about the branch and execute instructions tentatively, not storing their results until it knows if the branch will definitely be taken/not-taken.

If it guesses correctly then everything is good and the tentative instructions can retire. If it guesses incorrectly the pipeline must be flushed and refilled with the correct instructions. This can create a significant delay so it’s important to guess accurately.

A simple and reasonable branch predictor (modern CPUs probably use something much more complex) can be implemented with a single bit for every entry. The CPU will take the low bits of the current program counter (aka instruction pointer) and use this to index into a table of entries where it stored the result of the last branch that matched this entry. If that entry is a 1 then the branch was taken last time and will probably be taken this time, if it was 0 then the branch was not taken. When a branch instruction is retired then the "takenness" is stored in the matching entry.

This is similar to looking up the cache line or set for a memory access. Where it’s different is that collisions don’t matter, they only result in an incorrect prediction which may slow down the program, not an incorrect result.

A more advanced version might have N bits per entry, storing the most recent N results of the matching branches and perform some computation such as if there are more 1s than 0s to determine if the branch is likely to be taken again.

Shadow stack

x86 and x86_64 use call and ret instructions to implement a call stack. They’re not necessary as the sp/esp/rsp register can be manipulated directly, but they’re the typical instructions that compilers generate for procedure calls.

Modern x86/x86_64 chips accelerate them by buffering the values pushed on the stack by the call instruction and using this buffer to accelerate ret instructions. It is more of a buffer than a cache, but I wanted to include it anyway. If call and ret instructions become misaligned or the buffer under/overflows than a more general slow-path is used, so it’s not something the programmer or even the operating system needs to manage. It is something that you might wish to be aware of when optimising code though.

Remarks

I wanted to provide a breadth of information about CPU caches. If you want to go deeper on any particular topic I’m sure a web search will point you in the right direction, but hopefully I’ve collected a reasonable overview here.

Next time you hit a performance problem and you want to say "Oh probably cache" and dismiss the artifact, you now have a few clues for deeper investigation. One case where this came up was for the Mercury team (but before I joined the Mercury project). They improved Mercury's performance by ensuring that a bunch of memory regions were not aligned. With paged-aligned regions the commonly used addresses (near the bottom of each region) mapped to the same cache line or set and conflicted with each other. By randomising their alignment the team avoided this conflict and improved performance.

If you liked this article you might also like: x86 Addressing Under the Hood.

Recursive Lambdas In Plasma

Wed, 13 Feb 2019 00:00:00 +1100

While implementing closures in Plasma I hit this problem and think it might be an interesting example to demonstrate where theory and practice meet in programming language implementation.

Lambda expressions are anonymous (lambda expression means anonymous function). and because things need to be named so we can refer to them (in most languages) a lambda expression cannot refer to itself and be recursive. So why would I want to make them recursive? We’ll get to that, but first some background.

Statements in Plasma work like let expressions might in typical functional languages. The first statement here binds x and subsequent statements may now refer to it.

x = a + b
print!(int_to_string(x) ++ "\n")

x can’t be used before it is defined, including the right-hand-side of an binding (=) in the same statement. So this is illegal.

x = x + 1

Meanwhile functions are recursive:

func foo(x) -> Int {
   return foo(x + 1)
}

is legal, but not a good idea.

Next we want to support nested functions and lambda expressions. Nested functions look like:

func main() uses IO -> Int {
    greeting = "Hello "
    func hi(name : String) uses IO {
        print!(greeting ++ name ++ "\n")
    }

    hi!("Paul")
    return 0
}

And lambda expressions might look like:

func main() uses IO -> Int {
    greeting = "Hello "
    hi = func(name : String) uses IO {
        print!(greeting ++ name ++ "\n")
    }

    hi!("Paul")
    return 0
}

In fact, both are equivalent, and therefore, to keep the compiler and other tools simpler one is usually implemented in terms of the other. Often as a "syntax sugar" (but not always). In the case of functions in Plasma, the lambda expression is more general, so we’ll implement the nested function definitions in terms of lambda expressions. (In Plasma this is not a syntax sugar since the desugaring of nested functions happens at a later compilation stage, after parsing.)

Everything is fine until we attempt recursion.

func length(l : List(x)) -> Int {
   match (l) {
      case [] -> {
         return 0
      }
      case [x|xs] -> {
         return length(xs) + 1
      }
   }
}

If this is nested inside another function and implemented in terms of lambda, then it becomes:

length = func(l : List(x)) -> Int {
   match (l) {
      case [] -> {
         return 0
      }
      case [x|xs] -> {
         return length(xs) + 1      // UNDEFINED
      }
   }
}

And if we think about our x = x + 1 example above, we can’t access length before it has been bound. This is not only restrictive and surprising, but it’s also against one principal I have for Plasma, that is that the same thing (syntax-wise) should behave the same regardless of context. If this function was at the top level then it would not be transformed this way and would be able to be recursive. (A related principal is that things that look the same should be the same.)

Naturally if we wrote a lambda it should not be able to access itself. Maybe the above case looks okay, however:

greetings = map(func(name : String) -> String {
      return "G'day " ++ name
   }, names);

It makes no-sense for the lambda, which is very definitely an expression in map's first argument, to access the greetings variable. Because things that look the same (lambdas) should be the same, we need the same rule for the above length lambda as we do here.

That brings us to the decision that we have to make the lambda syntax, and nested function syntax behave differently even though they map to the same internal thing. This is where we may add some exceptions to the rules of our language’s internal consistency, in order to provide external consistency from the user’s perspective.

In my opinion, the solution isn’t the interesting part. What you just read, how we decide how to make a language consistent is the interesting part. Read on for how we usually solve this within a compiler.

When a function is defined as a statement, such as:

func length(l : List(x)) -> Int {
   ...
}

and we transform it to a statement containing an expression which is a lambda. The compiler can attach to the lambda the name it was defined with and the knowledge that it must be able to access its own name from within. Compilers attach a lot of data to the nodes that represent the program, this is just one other thing.

length = func(l : List(x)) Int
   #pragma lambda name "length"
   {
      ...
   }

Now when we process this lambda we know to make the name "length" refer to itself and to allow it to be resolved from within. And when performing later analyses we have to check such annotations.

What Plasma actually does is slightly more complex because it fits with the structure of the compiler better (and is not implemented yet). At the time when these statements are transformed to lambdas, a name for the function that tracks the lambda is generated (and used for other reasons) We can search the body of such functions to look for the name "length" and replace it with the internal name.

length = func lambda_23_length_2(l : List(x)) -> Int {
   match (l) {
      case [] -> {
         return 0
      }
      case [x|xs] -> {
         return lambda_23_length_2(xs) + 1
      }
   }
}

If you’re wondering where the numbers come from, they’re the line and column numbers from the source file, they’ll always be unique and this symbol won’t be exported.

Update 2019-02-13

The simple solution presented here won’t work for mutually recursive functions, which should work because they do work at the top level so they should work in nested levels. I think the solution here could be made to work, subject to other bindings and causality.

Happy Holidays

Fri, 21 Dec 2018 00:00:00 +1100

Last year, for over half a year I was in the practice of writing company-wide e-mails, bothering everyone at Mozilla, about why I wouldn’t be at work the next day due to a public holiday. It started with the most hilarious holiday the "Friday before the AFL grand final public holiday" (remind me this September, and I’ll explain) and finished after we got into some much less fun holidays such as invasion day (Jan 26th).

I remembered this recently and felt like sharing what I wrote for Christmas last year. Pretending that Christmas is something celebrated only in Australia and I had to explain it to the rest of the world, I wrote:

Australia will be celebrating two very significant local holidays this December 25th and 26th.

25th of December: Christmas Day.

On Christmas Day we celebrate the birth of Sir Isaac Newton, he is gracious enough to share his birthday with Jesus Christ (who is significant to many Australians, but not myself, so this e-mail will be mostly-secular).

The day begins with coffee (like every day) followed by gift-giving. Santa aka Father Christmas brings gifts for the children. Santa comes from the North Pole where it is winter all the time. In Australia it is summertime and there is no snow on the ground for his sleigh to work properly, so instead he rides on a firetruck. Also due to the heat Santa perspires a lot and needs to replace those fluids quickly, so it isn’t unusual to see Santa quickly drink a beer underneath his beard. The beard helps to conceal this from the children.

The main feast is called Christmas Lunch, it can consist of ham, roast chicken, roast pork and roast veggies or salads. Sometimes BBQd or boiled prawns are also served, I prefer boiled. No we don’t "throw another shrimp on the barbie" they’re called prawns. The meats are often served cold with salads since the weather is warm. If the weather is cold then serving them warm with roast veggies is also normal.

In our family and I gather in many others the afternoon is spent napping or with quiet activities like reading or board games. Children will often watch a film, many of the films feature cold weather and winter iconography.

December 26th: Boxing Day

This holiday is called Boxing Day after the Boxing Day test cricket match. We send our greatest champions out into 35-40c heat to play cricket against the champions of another nation with hot weather. Such as New Zealand, South Africa, West Indies, India, Pakistan, Sri Lanka, Zimbabwe, Bangladesh, and Afghanistan. We also let England and Ireland play even though they don’t have hot weather, but they did invent the game so we invite them anyway.

The cricket match can last up to 5 days. And although our champions have to spend this time in the hot weather. I believe this is really to the benefit of the spectators in their air-conditioned homes. They are socially permitted to watch sports for 5 days while drinking beer.

January 1st: New years day.

This is also a public holiday, but I got bored and didn’t write anything for it.

I hope you enjoy your local holidays, if you have them, otherwise enjoy your not-holidays.