Limits
Zero mode has no garbage collector, no exceptions you can catch, no async/await, no .NET LINQ, and almost no base class library. A good deal of ordinary C# still works, because zerocore provides the parts the compiler needs. This page lists both sides and the known issues, so you can tell early whether a design fits.
What works
With zerocore, as build.sh builds it:
- Classes, structs and generics, virtual methods, and interfaces, including default interface
methods. Every
newcallscallocand is never freed (see Memory without a GC). - Static abstract interface members and constrained generic calls.
- Casts:
(T)x,is,asand type patterns, to classes and interfaces. Boxing: a struct converted toobjector to an interface it implements. - Arrays:
new T[n], including arrays of strings, objects and interfaces, array initializers, andSpan<T>. - Static fields of every type, including strings, objects and arrays, and static constructors.
- Strings:
==,+(with numbers too:"n=" + 5),switch,ToString()andstring.Format, pluslib/for the rest (see Strings without a GC). - Records and anonymous types: value equality,
with, deconstruction and the generatedToString;typeofandGetType()for comparing types. With no reflection, aTypehas no name, and a class without its ownToStringprintsobject. - Delegates and lambdas (they allocate),
try/finallyandusing. - Function pointers, P/Invoke and
[UnmanagedCallersOnly]callbacks. - Threads:
Parallel.Forruns a loop on every processor, withInterlockedandVolatilefor shared state. There is noThreadclass orlock. MathandMathF, andMain(string[] args)and top-level statements.- Extension methods, and C# 14 extension members: properties, static members and
refreceivers inextension(...)blocks.
Records work as in .NET, including the generated ToString:
public record struct Point(int X, int Y);
public record Person(string Name, int Age);
public record Employee(string Name, int Age, string Team) : Person(Name, Age);
var a = new Point(1, 2);
var b = new Point(Opaque(1), 2);
Point moved = a with { Y = 5 };
Out.Line(a.ToString()); // Point { X = 1, Y = 2 }
Out.Line(moved.ToString()); // Point { X = 1, Y = 5 }
Extension members compile to ordinary static methods, so they cost nothing at run time:
public struct Vec
{
public int X, Y;
}
public static class VecExtensions
{
// Classic extension method: `this` on the first parameter.
public static int Dot(this Vec a, Vec b) => a.X * b.X + a.Y * b.Y;
// C# 14 extension block: properties and methods on a Vec value.
extension(Vec v)
{
public int LengthSquared => v.Dot(v);
public bool IsZero => v.X == 0 && v.Y == 0;
public Vec Scale(int k) => new Vec { X = v.X * k, Y = v.Y * k };
}
// Static members, called as Vec.Zero and Vec.Of(1, 2).
extension(Vec)
{
public static Vec Zero => default;
public static Vec Of(int x, int y) => new Vec { X = x, Y = y };
}
// By reference: changes the caller's variable.
extension(ref Vec v)
{
public void Translate(int dx, int dy)
{
v.X += dx;
v.Y += dy;
}
}
}
Vec v = Vec.Of(Opaque(3), Opaque(4));
Check("extension method", v.Dot(Vec.Of(1, 1)) == 7);
Check("extension property", v.LengthSquared == 25);
Check("extension method in a block", v.Scale(2).LengthSquared == 100);
Check("static extension members", Vec.Zero.IsZero && !v.IsZero);
v.Translate(-3, -4);
Check("by-reference extension", v.IsZero);
C# 15 unions work too. A union holds a value of one of the types it lists, and a switch on it
must handle each of them, which makes it the natural way to return an error:
public struct Parsed { public int Value; }
public struct BadChar { public int Position; }
// A ParseResult holds either a Parsed or a BadChar, and a switch on it must
// handle both.
public union ParseResult(Parsed, BadChar);
static ParseResult ParseNumber(string text)
{
int value = 0;
for (int i = 0; i < text.Length; i++)
{
char c = text[i];
if (c < '0' || c > '9')
return new BadChar { Position = i };
value = value * 10 + (c - '0');
}
return new Parsed { Value = value };
}
static int ValueOrMinusOne(string text) => ParseNumber(text) switch
{
Parsed p => p.Value,
BadChar => -1,
};
A union keeps its value in a field of type object, so a struct value is boxed: each Parsed or
BadChar returned above is a heap allocation that is never freed. That is fine for an error that
happens once, but not for a function called in a hot loop. There, return a struct with a tag field,
or allocate in an arena.
Casts to interfaces work as in .NET, except that a failed (T)x ends the program instead of throwing:
object circle = Opaque(new Circle { Radius = 2 });
object rect = Opaque(new Rect { W = 3, H = 4 });
object square = Opaque(new Square { W = 5, H = 5 });
object plain = Opaque(new Plain());
object nothing = Opaque(null);
Check("class implementing it directly", circle is IShape);
Check("second interface of a class", rect is IScalable);
Check("not implemented", !(circle is IScalable));
Check("unrelated class", !(plain is IShape));
Check("unrelated interface", !(rect is IUnrelated));
Check("null is never an instance", !(nothing is IShape));
Check("through the base class", square is IShape && square is IScalable);
Check("through another interface", circle is INamed && square is INamed);
Choosing how to dispatch
Interfaces and virtual methods both work, but they don't cost the same. An interface call the compiler can't resolve at build time goes through a small cache per call site: a little slower than a virtual call, and slower again at a site that sees more than four classes.
Generics with static abstract members avoid the question. They are resolved at compile time, one specialized copy per struct type, with no allocation and no indirect call. That suits hot loops such as per-format compute kernels:
public interface IArea<TSelf> where TSelf : struct, IArea<TSelf>
{
static abstract string Name { get; }
static abstract int Area(in TSelf shape);
}
public struct Rect : IArea<Rect>
{
public int W, H;
public static string Name => "Rect";
public static int Area(in Rect r) => r.W * r.H;
}
static void PrintArea<T>(in T shape) where T : struct, IArea<T>
{
Out.Write(T.Name);
Out.Line(" area: ", T.Area(in shape));
}
What doesn't work
- Freeing memory. Nothing allocated with
new, boxing or+is ever freed. Use arenas for anything short-lived. - Catching exceptions.
throwis a panic, like Rust'spanic!built withpanic = "abort": it prints the exception's message and ends the program. Nothing unwinds, so nocatchblock runs, and neither do thefinallyblocks andusingdisposals between thethrowandMain. A failure that would throw in .NET, such as a failed cast, an index out of range or an overflow incheckedcode, ends the program the same way. A null dereference is a plain segmentation fault.lib/follows the same rule: when it catches a mistake, it can only end the program with a message. Return errors as values instead, for example with a union (see above). - Variance. Casting or dispatching through it (
IEnumerable<string>asIEnumerable<object>,string[]asobject[]) aborts with a message saying so, instead of answering wrongly. - Most of the base class library. No
Console(useOutandIn), no .NET collections (uselib/'s), no LINQ (uselib/Seq.cs), no reflection (aTypeonly compares), async,Thread,Half, or boxing ofNullable<T>. - A struct's default
Equalscompares bytes. A reference field compares by reference, where .NET would call itsEquals. Records andIEquatable<T>compare field by field. - Reflection. Builds need
--no-reflection. - Run-time CPU detection. Instruction sets beyond the baseline are available only when the build
names them with
-m. - Some platforms. zerocore runs on Linux (x64, arm64), macOS on Apple Silicon, Windows x64,
WebAssembly and DOS. Not on Windows on arm64 or Intel Macs. And Windows programs are built from
Linux or macOS: building on Windows (
build.ps1) is untested and uses bflat's zerolib.
zerocore/README.md has the full list.
Known issues and workarounds
These are the issues you may hit with zerocore, as build.sh builds:
| Issue | Workaround |
|---|---|
[DllImport] of a library not passed with -i fails to compile ("Expected type 'Internal.Runtime.CompilerHelpers.InteropHelpers' not found") |
Pass -i <library>; build.sh passes -i libc -i libm.so.6 |
Building without --no-reflection fails ("Failed to load type 'Internal.Metadata.NativeFormat.TypeDefinition'") |
Pass --no-reflection; build.sh does |
Non-baseline instruction sets (AVX2, FMA, dotprod) report IsSupported == false |
Build with -m x86-64-v3 or -m dotprod; build.sh does this for Simd and Kernels |
No Console, Half, Thread |
lib/Out.cs for output, lib/In.cs for input; Parallel.For (lib/Threads.cs) for threads |
"n=" + 5, ToString() and string.Format allocate a string that's never freed |
Fine once; in a loop, Str.Format(arena, $"n={5}") |
| Casts and interface calls that need variance abort at run time | Not supported |
| Windows: x64 only, built from Linux or macOS | ./build.sh --win; building on Windows (build.ps1) is untested |
| macOS: Apple Silicon only, built on a Mac | ./build.sh --mac |
Two of these come from the core library having to be named System.Private.CoreLib. bflat assumes a
library with that name is .NET's and looks for its reflection support, hence --no-reflection. And
without -i, bflat binds a [DllImport] function when it is first called, which needs runtime support
zerocore doesn't have; with -i, it is bound at link time.
The other targets add limits of their own: no SIMD and no callbacks from native code on WebAssembly, one thread and a 387 for floating point on DOS. Targets covers them.
Errors from the compiler
Most of zerocore is a contract with the compiler, which looks types, methods and fields up by name
(System.Runtime.TypeCast.CheckCastClass, String._stringLength, ...). When one it needs is missing,
the build fails with "Expected type ... not found" or "Failed to load type ...", not with a C# error.
Those names can't be changed. If you see such a message, check the first two rows of the table above
before anything else.