The Nim memory model

A computer’s main memory (RAM) consists of a lot of memory locations, each of which has an unique address. Depending on the CPU architecture the size of each memory location (the "word size") typically varies between one byte (8 bit) to eight bytes (64 bit), while the CPU is usually also able to access large words as smaller chunks. Some architectures can read and write memory from arbitrary addresses, while others can only access memory at addresses which are a multiple of the word size.

The CPU accesses memory using specific instructions that allow it to read or write data of a given word size from or to a given address. For example, it might store the value 0x12345 as a 32 bit number at address 0x100000. The low level assembly instruction for doing this might look something like this:

This is what the memory on address 0x100000 will look like after the above instruction completes, with each column representing a byte:

To complicate things a bit more, the actual order of bytes within a word varies between CPU types - some CPUs put the most significant byte first, while others put the least significant byte first. This is called the endianess of a CPU.

Most important of all: if you want to write portable code, do not ever make any assumptions about your machines endianess when writing binary data to disk or over the network and make sure to explicitly convert your data to the proper endianess.

A stack is a region of memory where data is always added and removed from one end. This is called "last-in-first-out" (LIFO).

Next to the stack, the heap is the other place to store data in a computer program. While the stack is typically used to hold local variables, the heap can be used for more dynamic storage.

Basically, a pointer is nothing more then a special type of variable which holds a memory address — it points to something else in memory. As briefly mentioned above, there are two types of pointers in Nim:

The ptr T pointer type is considered unsafe. Pointers point to manually allocated objects or to objects somewhere else in memory, and it is your task as a programmer to make sure your pointers always point to valid data.

When you want to access the data in the memory that the pointer points to — the contents of the address with that numerical index — you need to dereference (or in short, deref) the pointer.

In Nim you can use an empty array subscript [] to do this, analogous to using the * prefix operator in C. The snippet below shows how to create an alias to an int and change its value.

For object or tuple access, Nim will perform automatic dereferencing for you: the normal . access operator can be used just as with a normal object.

Local variables (also called automatic variables) are the default method by which Nim stores your variables and data.

Nim will reserve space for your variable on the stack, and it will stay there as long as it is in scope. In practice, this means that the variable will exist as long as the function in which it is declared does not return. As soon as the function returns the stack unwinds and the variables are gone.

Here are some examples of variables which will be stored on the stack:

In the previous sections we saw that pointers in Nim as returned by addr() are of the type ptr T, but we saw that new returns a ref T.

While both ptr and ref are pointers to data, there is an important difference between the two:

The only way to acquire a ref T pointer is to allocate the memory using the new() proc. Nim will reserve the memory for you, and also will start keeping track of where in the code this data is referenced. When the Nim runtime sees that the data is no longer referred to, it knows it is safe to discard it and it will automatically free it for you. This is known as garbage collection, or GC for short.

A primitive or scalar type is a "single" value like an int, a bool or a float. Scalars are usually kept on the stack, unless they are part of a container type like an object.

Let’s see how Nim manages memory for primitive types for us. The snippet below first creates a variable a of type int and prints this variable and its size. Then it will create a second variable b of type ptr int which is called a pointer, and now holds the address of variable a.

On my machine I might get the following output:

The above can be represented by the following diagram:

Let’s put a more complicated object on the stack and see what happens:

In Nim, an object is just a way of grouping variables into a handy container, making sure they are placed next to each other in memory the same way as C would do.

Here is the output on my machine:

Lets go through the output:

So, let’s draw a little picture of what we have learned from the above:

So this is what our Thing object looks like in memory. So what is up with the hole marked ?? at offset 5, and why is the total size not 7 but 8 bytes?

This is caused by something the compiler does which is called alignment, to make it easier for the CPU to access the data in memory. By making sure objects are nicely aligned in memory at a multiple of their size (or a multiple of the architecture’s word size), the CPU can access the memory more efficiently. This usually results in faster code, at the price of wasting some memory.

(You can hint the Nim compiler not to do alignment but to place the fields of an object back-to-back in memory using the {.packed.} pragma — refer to the Nim language manual for details)

The above sections described how Nim manages relativily simple static objects in memory. This section will go into the implementation of more complex and dynamic data types which are part of the Nim language: strings and seqs.

In Nim, the string and seq data types are closely related. These are basically a long row of objects of the same type (chars for a strings, any other type for seqs). What is different for these types is that they can dynamically grow or shrink in memory.