The memory safety rules
Zero-mode code uses pointers more than ordinary C# does: arenas hand out pointers, collections keep
them, and C functions take them. The samples and lib/ compile under C# 15's
updated memory safety model,
which is in preview. This page explains what those rules say and how this repository uses them to
mark the places where memory can go wrong.
Turning the rules on
The rules are a compiler feature. The bflat fork adds a --compiler-feature option, the same as
csc -features:, and build.sh passes it, with the preview language version, to every build of
lib/ and the samples:
CSHARP_FLAGS=(--langversion preview --compiler-feature updated-memory-safety-rules)
zerocore is built with --langversion preview only. The editor projects turn the rules on for every
project (Directory.Build.props), so VS Code flags the same memory-safety errors in lib/ and the
samples that bflat does.
The three rules
Pointers are safe to create, unsafe to use. Pointer types, &, stackalloc and fixed work in
safe code. Dereferencing (*p, p->x, p[i]) and calling function pointers need an unsafe { }
block. So the unsafe block sits on the line that uses a pointer, not on everything that touches
one.
unsafe on a member is a contract. A member marked unsafe can only be called from an unsafe
context, so every caller has to opt in. Marking a member doesn't make its body unsafe: the body still
needs inner unsafe { } blocks where it dereferences.
Every extern says safe or unsafe. A P/Invoke declaration states whether calling it can break
memory safety. In lib/Arena.cs, for example:
static safe extern void* malloc(nuint size);
static unsafe extern void free(void* ptr);
malloc only returns a pointer, which is harmless until it is used. free can leave every pointer
into that memory dangling, so its callers must opt in.
Allocating is safe, freeing is not
lib/Arena.cs follows the same reasoning as malloc and free. Allocating from an arena is safe: you
get a pointer, and using that pointer needs unsafe anyway. Reading and writing through it is where
the unsafe blocks go:
Entity* e = arena.Alloc<Entity>();
int* squares = arena.AllocArray<int>(10);
unsafe
{
e->Id = 1;
e->Position.X = 100;
for (int i = 0; i < 10; i++)
squares[i] = i * i;
Out.Line("squares[5] = ", squares[5]);
}
The dangerous operations are the ones that free memory: Restore(), Reset(), Destroy() and
OpenScope(). Calling one of them is what turns other pointers, spans and collections into dangling
ones, so they are marked unsafe. Nothing else can check that promise: an arena doesn't know who still
holds a pointer into it, and by default a stale pointer still reads memory that looks valid (see
Memory without a GC).
So the unsafe keyword in this code base points at two kinds of line: those that dereference a
pointer, and those that free memory something else may still point at. A search for unsafe finds
every place that needs a second look.
SAFETY comments
An unsafe block says that something here can go wrong. It doesn't say why it doesn't. The
repository's convention is to write that down: an unsafe block that relies on a promise carries a
// SAFETY: comment with the reason it is correct.
// Temporary strings: free them with Restore and keep the rest.
nuint usedBefore = s_arena.Used;
Arena.Mark mark = s_arena.Save();
string temporary = Str.Format(s_arena, $"{name} has {name.Length} letters");
bool temporaryOk = temporary.EndsWith("3 letters");
unsafe { s_arena.Restore(mark); } // SAFETY: temporary is not used below.
The comment states what the caller promises, here that temporary isn't used after the restore. A
reviewer checks the comment against the code below it instead of reasoning about the whole function.
lib/ does the same inside its own implementation ("a live header", "CheckIndex validated header and
index"), and where one argument covers many blocks, a single comment says so once.
The same idea applies to members. Each unsafe member in lib/ documents its contract in a
<safety> section of its doc comment. Arena.Restore says that every pointer, span and collection
allocated since the mark becomes dangling, including the buffer of an older collection that grew after
the mark. The Arena reference shows those sections.
What the rules don't do
The rules mark where memory can go wrong; they don't check it. A SAFETY comment is a claim, and a
wrong claim compiles. Two tools in lib/ catch some wrong claims at run time:
Arena.Restoreends the program for a mark from another arena or from before aReset(), and for most marks restored out of order.OpenScope()rules out the ordering mistake altogether.Arena.DebugChecksmakes freed memory read as0xDDbytes and makes collections stop the program when used after their memory was freed.
Catch arena mistakes shows both. Neither catches a stale pointer into memory that has since been handed out again, so the comment remains the main defense.