How autofree works

[medvednikov]

Due to many requests, I'll be writing down the principles of how autofree works. It will give a more transparent view into one of V's memory management models and will make it easier to contribute to the autofree engine, which is still work in progress.

Autofree is one of 4 ways to handle memory in V. The default one is a tracing GC, there's arena allocation with -prealloc, and manual memory management via -gc none.

There's a demo video available. Building the Ved editor with autofree and running it on an 8MB text file with 0 leaks:
https://www.youtube.com/watch?v=gmB8ea8uLsM

When I started working on V, I was very anti-GC, expecting them to be slow and use a lot more RAM. I integrated a GC just for a test, and was surprised at how well it worked with V, a very minimal language, that avoids doing unnecessary allocations in the first place by using value types, string buffers, promoting a simple abstraction-free code style. V's standard library doesn't use the GC, so turning it off for you application is not a problem (no need to use a different version of stdlib etc).

What started as a test and a temporary way to allow developers to write leak free programs, became the stable and well working default option. Autofree in fact performed a bit worse than the default GC. The reasons will be explained in this article.

Other things in the compiler were prioritized, that's why autofree still isn't finished yet. But it is important, and it will be finished. Very often using a GC is simply not an option. For examples in drivers and kernels. In fact, our Vinix kernel uses autofree.
Our goal is to make V very flexible and configurable, that's why we provide multiple ways to manage memory.

As the home page explains, autofree frees the variables that the compiler knows it can safely free. For all the remaining cases, the GC is used with an option to use manual memory management (in the future the compiler will point out the variables it can't free if -gc none is used).

The amount of such variables can vary depending on the code. It should be about 10% on average. In the mentioned Ved demo, 0% of variables are unhandled by autofree.

Let's go through what autofree can handle and what it does.

1. Simple out of scope variables.

If a variable results in an allocation, and this allocation is not used anywhere else, the variable is freed at the end of the block it was created in (i.e. the variable goes out of scope):

fn foo() {
	s1 := 'hello'
	s2 := 'world'
	s := s1 + ' ' + s2 // string concatenation results in a heap allocation
	println(s)

	foo := &Foo{} // struct allocated on heap
	foo.bar()

	s.free() // inserted by autofree
	foo.free() // inserted by autofree
}

fn main() {
	foo()
}

In this example I didn't use s := 'hello ' + 'world', because V's optimizer will simplify it to s := 'hello world', and simple string literals don't result in an allocation. Literals are also detected by the codegen itself and skipped, so you won't see useless free() calls on them.

"Not used anywhere else" has a precise meaning in the compiler. A variable is left alone when:

• it is returned from the function (the codegen walks the return expression and records the names it sees, including struct field initializers like return Foo{ x: s });
• it is captured by a closure or inherited into an inner scope;
• it is initialized inside an or {} block (those temporaries are emitted after the block in C, so freeing them at scope exit would be wrong);
• it is a function argument (those are freed by the caller, not the callee);
• it is a for loop variable (for i, v in list).

Everything else gets a free() call inserted at the end of its scope.

2. Allocated strings are cloned on assignments.

To ensure that string copies do not point to freed memory, they are always cloned. This is an expensive O(n) operation, and is one of the reasons autofree can be slower than V's default GC or manual management. It can be optimized by doing copy on write and more analysis by the compiler.

fn do_stuff(s string) {}

fn foo() {
	s1 := 'hello'
	s2 := 'world'
	s := s1 + ' ' + s2
	str_copy := s
	do_stuff(str_copy)
}

This results in:

fn foo() {
	s1 := 'hello'
	s2 := 'world'
	s := s1 + ' ' + s2
	str_copy := s.clone() // inserted by autofree
	do_stuff(str_copy)
	str_copy.free() // inserted by autofree
	s.free()        // inserted by autofree
	// s1, s2 are string literals - not freed
}

This is only about strings, not arrays. Note that V forces cloning arrays on assignment, even without autofree enabled:

a.v:30:4: error: use `array2 := array1.clone()` instead of `array2 := array1` (or use `unsafe`)
   28 |
   29 |     a := [1,2,3]
   30 |     b := a
      |       ~~
   31 | }

The "autofree is sometimes slower than GC" question deserves a fuller answer than just "cloning". The other reason is that autofree frees eagerly at scope exit. A function that creates ten short-lived strings in a loop body will pay ten free() calls per iteration. The Boehm GC, on the other hand, batches reclamation and only runs when it has to. For programs that allocate in tight loops and let go of allocations almost immediately, batched reclamation can win. For programs with longer-lived allocations (like Ved, which keeps a large text buffer around), autofree's eager strategy is a clear win — there's no scan, no pause, no tracing.

3. Temporary expressions inside function calls.

If you write do_stuff(a + b), the result of a + b is a heap-allocated string with no name. Autofree can't free what it can't see, so the compiler hoists the temporary into a synthetic variable:

fn foo() {
	do_stuff('hello ' + name)
}

becomes, roughly:

fn foo() {
	_arg_expr_do_stuff_0 := 'hello ' + name
	do_stuff(_arg_expr_do_stuff_0)
	_arg_expr_do_stuff_0.free() // inserted by autofree
}

The same mechanism handles string interpolation. 'x=${expr}' is split into a string builder that produces a temporary; the temporary is registered in the scope with an internal flag and freed right after it stops being needed.

For method calls, the receiver gets the same treatment when it's a temporary expression: ('a' + 'b').contains('ab') will free the concatenation result after contains returns.

4. Recursive freeing of structs, arrays, maps, sumtypes and interfaces.

Calling s.free() on a string is trivial — it's one free() of one buffer. Everything else is recursive, and the compiler generates a dedicated free function per type. Given:

struct User {
	name    string
	emails  []string
	friends map[string]int
}

the compiler emits a User_free that frees name, walks emails freeing each element and then the backing array, frees the map, and finally releases the struct itself if it was heap-allocated. The same idea extends to:

• arrays — array_T_free frees every element via T_free and then the array.
• maps — keys and values are freed recursively, then the table.
• sumtypes — a switch on the type tag frees only the active variant's payload.
• interfaces — dispatch through the interface's type table to call the concrete type's free function.
• option fields — guarded by a state != 2 check, so uninitialized options are never freed.

If you define a free() method on your own type, the compiler uses yours instead of generating one. This is the escape hatch for types that own resources the compiler doesn't know about (file handles, sockets, mmap regions, etc).

5. What autofree does not handle yet.

It's more honest to list the limitations than to repeat the "90%" number.

• User reference types (&Foo) are only freed under -experimental. Without that flag, pointer locals to user types are silently left to the GC.
• Channels, threads, function values, raw voidptr allocations have no free codegen.
• Multi-return assignment (a, b := f()) doesn't carry an expression into the var, so the string-literal check from §1 can't fire and a temporary string_free is emitted even when one side was a literal.
• Returning a wrapped variable is not always recognized. return x is fine. return Foo{ x: x } is fine. return [x] or return f(x) will currently free x before the caller gets it.
• Generic types are skipped while their type parameters are still unresolved.

These are not design limits — they are missing cases. Each one corresponds to a TODO: somewhere in vlib/v/gen/c/autofree.v or auto_free_methods.v.

6. Early returns and freeing across nested scopes.

The end-of-scope rule isn't enough on its own. Consider:

fn foo() {
	s := some_string()
	for line in lines {
		buf := line.repeat(2)
		if buf.contains('bug') {
			return // s and buf both need to be freed here
		}
	}
}

When the codegen sees return, it walks the chain of parent scopes and emits frees for every live variable in each one, stopping at the function boundary. Variables that appear in the return expression itself are marked as "returned" and skipped, so return s correctly hands ownership to the caller. break and continue work the same way, except they stop at the enclosing loop instead of the function.

7. Opting out: @[manualfree] and @[reused].

Two attributes let you steer the engine.

@[manualfree] on a function disables autofree inside that function's body. The standard library uses this in hot paths and in places where the compiler doesn't yet know how to reason about lifetimes correctly. You can also put it on a module declaration to opt the whole module out.

@[manualfree]
fn hot_path(s string) string {
	// no free() calls inserted; you free what you allocate
}

@[reused] is the opposite of an escape hatch — it's a hint to autofree. It marks a method that recycles its receiver's existing allocation rather than producing a new one (think of clear() on a string builder). Without the hint, autofree might free a literal that the method intends to reuse; with the hint, the literal is left alone.

The builtin module is special-cased: autofree never touches it, because the builtin types are what autofree calls into.

8. Current state and what's next.

The pieces above are real, in the compiler today, and exercised by the autofree tests under vlib/v/tests/ and the valgrind suite under vlib/v/slow_tests/valgrind/. The known gaps (§5) are the priority list. The bigger longer-term items are:

• copy-on-write for strings, to remove most of the cloning cost from §2;
• proper escape analysis, so the compiler can promote more allocations to the stack and skip both the free and the GC entirely;
• a diagnostic mode (-gc none + a flag) that reports every variable autofree couldn't handle, so the remaining manual work is visible.

Autofree is not the only memory management option in V, and it doesn't have to be. The goal is that you can pick the model that fits the program: GC for normal application code, autofree for kernels and drivers, arenas for short-lived batch jobs, manual for the last 1%. The same language, the same standard library, the same code.

[MatejMagat305]

(I do not know whether I can, but I have small note)
note:
on the one thread it is true (GC is better), but on multicore is better autofree (at least some case), because GC limit to 1.2 cores ... maybe only in some case
but Vlang is gratefull language ...!

[ArtemkaKun]

We can also try to use/implement multithreaded GC. Java experience shows that this is the future of GC.

[Wajinn]

Autofree is one of 4 ways to handle memory in V. The default one is a tracing GC, there's arena allocation with -prealloc, and manual memory management via -gc none.

Strongly believe that this kind of post and upcoming article is important to help neutralize some of the confusion and deceptive criticisms placed out there. Among the things that are done: 1) Critics who like pretending they don't know anything about V's memory management options. 2) Pretending not to understand what the words "option" or "optional" means, or that V's GC can be turned off. 3) Ridiculous smears of over any GC usage, as if it means to somehow be "inferior".

That V uses an optional GC by default is tremendously helpful and convenient to new and casual programmers. Not only that, (in addition to other safety features that V has), it provides a degree of memory safety which has repeatedly been recommended by various government organizations. Consequently, people can get started being productive with V much more rapidly, because they don't have to worry about manual memory management. They can more rapidly focus on getting results and solutions. When ready, the GC can be turned off, because they are actually dealing with a situation where doing so would be useful or are really that advanced of a programmer.

As V is a compiled programming language, whose optional GC can be turned off, means it can go about memory management in a number of ways that is highly competitive to any that exists. Thus arena allocators. Optional GC and arena allocator usage, can be more than enough to offset excessive fixation on autofree until it becomes more developed and advanced. These other options should definitely get more attention in the documentation.

V is definitely more than just being about autofree (which is a great feature and option), it's a good and useful programming language. Autofree is more like a "cherry on top". The addition of autofree, with the other memory management options, strengthens the already existing benefits of using V.

[MatejMagat305]

I m sorry if I tell somethig what sound like that I criticise V have GC, GC is amazing tool when person do not need optimalization ..., and I realy llove V s options and their combinations, really amazing job!

[ArtemkaKun]

Criticizing V is ok if there are proofs 😅

I just said that GCs in development all the time, since big languages like Java or C# relays only on GC, so GC can be good too (somewhere in the future). Ofc combination of autofree and GC will be superior in my opinion

[Ddiidev]

Criticizing V is ok if there are proofs 😅

I just said that GCs in development all the time, since big languages like Java or C# relays only on GC, so GC can be good too (somewhere in the future). Ofc combination of autofree and GC will be superior in my opinion

I use C# a lot.
And the truth is that for most things you don't need to change much because the .NET GC has evolved a lot (mainly .NET7), and it has been doing something that V was born doing, which is to reduce allocations by improving the generational heuristic , etc...

I liked the initial idea of autofree in V, but I realized that in the end the GC delivers very well!

[Wajinn]

Looking at this. I think this should also be put in V's official Blog (https://blog.vlang.io/), when ready. As it would have a better "aesthetic" and be more "linkable", in addition to be a place where new users can update themselves on things being emphasized for them to know.

[Anivie]

The article seems to lack an explanation of why autofree leads to worse performance compared to enabling GC?

[Wajinn]

The article seems to lack an explanation of why autofree leads to worse performance compared to enabling GC?

Actually, if we read carefully, it does give a "partial" explanation.

2. Allocated strings are cloned on assignments.

To ensure that string copies do not point to freed memory, they are always cloned. This is an expensive O(n) operation, and is the main reason autofree can be slower than V's default GC or manual management.

GC works unexpectedly well with V, because of its design. Though interestingly and recently, V has some upgraded string performance optimizations, so it looks like a recheck of its affects on this topic are necessary.

I integrated a GC just for a test, and was surprised at how well it worked with V, a very minimal language, that avoids doing unnecessary allocations in the first place by using value types, string buffers, promoting a simple abstraction-free code style.

We also have to keep in mind that V is a compiled language, so GC usage isn't as slow as some people might be thinking or don't know any better are saying, like as is the case in scripting or interpreted languages. Seems more experimentation is being done, to get greater performance, which is great for V users.

Autofree and arena allocators will likely always have a seat at the table, because GC is not best or usable in all cases. Thus the flexible memory management as described on the website. GC, in the case of V and its design, is a highly usable default to start with.

[Anivie]

After reading the documentation, it is clear that autofree can only resolve 90% of resource releases in most cases, so it doesn't seem to work on its own

[Wajinn]

After reading the documentation, it can be understood that autofree can only solve 90% of the release issues in most cases, therefore, it seems that it cannot work independently.

Presently, that's correct. But, it depends on the program and programmer, as to what that remaining percentage will be. It's also unclear if the remaining percentage might not be able to get to, if autofree were run without the GC as fallback, would be acceptable for the use case. Depending on how long the program intends to run, a "slow leak" could be acceptable and it would ordinarily never cause a problem. We should also keep in mind that the usage of the autofree option, can be easy enough. Particularly as it becomes more polished.

Additionally, some other form of GC or memory management could possibly be used to resolve the remaining percentage. It looks like a question of further study (which is happening), as to what's best. But clearly we already have a usable language and default that usually doesn't leak, is easy for many users, and is memory safe. The other options are about greater efficiency or best solution possible, which is a good problem to have.

[Jengro777]

1. GC + Autofree (This is the default)
2. GC
3. Autofree
4. Manual

[i582]

Nope:

1. GC only (default)
2. Arena (-prealloc)
3. Autofree (-autofree)
4. Manual (-gc none)

[Jengro777]

1. GC only (default) v run main.v
2. Arena (-prealloc) v -prealloc run mian.v
3. Autofree (-autofree) v -autofree run main.v
4. Manual (-gc none) v -gc none run .v

[ntrel]

If a variable results in an allocation, and this allocation is not used anywhere else, the variable is freed at the end of the block

Does not used anywhere else mean it isn't returned or its address taken? What about if it is assigned to something, is an implicit clone inserted for heap structs?

(2) seems to be missing the local string allocation's call to free:

fn foo() {
	s1 := 'hello'
	s2 := 'world'
	s := s1 + ' ' + s2
	str_copy := s.clone() // inserted by autofree
	do_stuff(str_copy)
	s.free() // inserted by autofree?
}

more to come soon

Was there any update on this? Presumably at least when a reference to heap memory is reassigned to something else, the original memory is also freed if unused?

[Jengro777]

Autofree has been waiting too long, do I have to wait for another year or even longer

[Wajinn]

Autofree has been waiting too long, do I have to wait for another year or even longer

Seems a little pushy, when looking at this and the other thread (#20489), because the maintainer and other developers have responded to similar.

From the maintainer (last month and thread is linked above), "Autofree is not finished and not a priority until V 0.6, but it will be finished."

There is the GC to use, which covers most people. Really advanced users, can turn it off and manage manually. Maybe consider explaining what you are trying to do specifically and making the project public or at least put portions of code up on discord.

[Jengro777]

Autofree has been waiting too long, do I have to wait for another year or even longer

Seems a little pushy, when looking at this and the other thread (#20489), because the maintainer and other developers have responded to similar.

From the maintainer (last month and thread is linked above), "Autofree is not finished and not a priority until V 0.6, but it will be finished."

There is the GC to use, which covers most people. Really advanced users, can turn it off and manage manually. Maybe consider explaining what you are trying to do specifically and making the project public or at least put portions of code up on discord.

Autofree is what I am looking forward to, I will continue to wait

[StunxFS]

Imho, I think that autofree should work with ARC, and not the way it currently "works", that way it would save a lot of having to use .clone() and memory management would be more lightweight.

[medvednikov]

I've updated the blog post.