Baseline: tree as shared

This commit is contained in:
alexm committed 2026-10-05 03:03:38 +00:00
commit 31f2fb8a5a
1679 files changed
+1024562

No files matched your search

@@ -0,0 +1,329 @@
struct ImmutRef[origin: ImmOrigin]:
pass
```
Or you can use the [`Origin`](/docs/std/origin/Origin/)
struct to specify an origin with parametric mutability:
```mojo
struct ParametricRef[
is_mutable: Bool,
//,
origin: Origin[mut=is_mutable]
]:
pass
```
Origin types carry the mutability of a reference as a boolean parameter value,
indicating whether the origin is mutable, immutable, or even with mutability
depending on a parameter specified by the enclosing API.
The `is_mutable` parameter here is an [infer-only
parameter](/docs/manual/parameters/#infer-only-parameters). The `origin` value
is often inferred, as well. For example, the following code creates a
[`Pointer`](/docs/std/memory/pointer/Pointer/) to an existing value, but
doesn't need to specify an origin—the `origin` is inferred from the existing
value.
```mojo
from std.memory import Pointer
def use_pointer():
var a = 10
var ptr = Pointer(to=a)
```
### Origin sets
An `OriginSet` is not a type of origin, it represents a group of origins. Origin
sets are used for tracking the lifetimes of values captured in parametric
closures.
An `OriginSet` **isn't** a general-purpose mechanism for expressing a
combination of multiple origins. Instead, you can use `origin_of()` to express
an [origin union](#origin-unions).
### Origin values
Most origin values are created by the compiler. As a developer, there are a
few ways to specify origin values:
- Static origin. The `ImmStaticOrigin` `comptime` value
represents immutable values that last for the duration of the program.
String literal values have a `ImmStaticOrigin`.
- Derived origin. The `origin_of()` magic function returns the origin
associated with the value (or values) passed in.
- Inferred origin. You can use inferred parameters to capture the origin of a
value passed in to a function.
- Untracked origins. The untracked origins, `MutUntrackedOrigin` and
`ImmUntrackedOrigin` represent values that are not tracked by the lifetime
checker, such as dynamically-allocated memory.
- Wildcard origins. The `ImmUnsafeAnyOrigin` and `MutUnsafeAnyOrigin`
`comptime` values are special cases indicating a reference that might access
any live value.
#### Static origins
You can use the static origin `ImmStaticOrigin` when you have a
value that exists for the entire duration of the program.
For example, the `StringLiteral` method
[`as_string_slice()`](/docs/std/builtin/string_literal/StringLiteral/#as_string_slice)
returns a [`StringSpan`](/docs/std/collections/string/string_span/StringSpan/)
pointing to the original string literal. String literals are static—they're
allocated at compile time and never destroyed—so the slice is created with an
immutable, static origin.
#### Derived origins
Use the `origin_of(value)` operator to obtain a value's origin. An argument
to `origin_of()` can take an arbitrary expression that yields one of the
following:
- An origin value.
- A value with a memory location.
For example:
```mojo
origin_of(self)
origin_of(x.y)
origin_of(foo())
```
The `origin_of()` operator is analyzed statically at compile time;
The expressions passed to `origin_of()` are never evaluated. (For example,
when the compiler analyzes `origin_of(foo())`, it doesn't run the `foo()`
function.)
The following struct stores a string value using a
[`OwnedPointer`](/docs/std/memory/owned_pointer/OwnedPointer/): a smart
pointer that holds an owned value. The `as_ptr()` method returns a `Pointer` to
the stored string, using the same origin as the original `OwnedPointer`.
```mojo
from std.memory import OwnedPointer, Pointer
struct BoxedString:
var o_ptr: OwnedPointer[String]
def __init__(out self, value: String):
self.o_ptr = OwnedPointer(value)
def as_ptr(mut self) -> Pointer[String, origin_of(self.o_ptr)]:
return Pointer(to=self.o_ptr[])
```
Note that the `as_ptr()` method takes its `self` argument as `mut self`. If it
used the default argument convention, it would be immutable, and the
derived origin (`origin_of(self.o_ptr)`) would also be immutable.
You can also pass multiple expressions to `origin_of()` to express the union
of two or more origins:
`origin_of(a, b)`
#### Origin unions
When a function returns a reference or pointer that can have one of several
different origins, you can express the referenced origin as a union of all
of the possible origin values.
The union of two or more origins creates a new origin that references all of the
original origins for the purposes of lifetime extension (so a union of the
origins of `a` and `b` extends both lifetimes). An origin union is mutable if
and only if all of its constituent origins are mutable. Use an origin union
For an example, see
[Return values with union origins](#return-values-with-union-origins).
#### Inferred origins
Since origins are parameters, the compiler can *infer* an origin value from
the argument passed to a function or method, as described in
[Parameter inference](/docs/manual/parameters/#parameter-inference). This allows
a function to return a value that has the same origin as the argument passed to
it.
See the section on [`ref` arguments](#ref-arguments) for an example using an
inferred origin.
#### Untracked origins
The untracked origins, `MutUntrackedOrigin` and `ImmUntrackedOrigin` represent
values that do not alias any existing value. That is, they point to memory that
is not owned by any other variable, and are therefore not tracked by the
lifetime checker. For example, the
[`alloc()`](/docs/std/memory/alloc/alloc/) function returns an
`Allocation` for a new dynamically-allocated block of memory, with the origin
`MutUntrackedOrigin`. The origin indicates that the memory is not managed by the
Mojo ownership system. When you use an unsafe API like this, you're responsible
for managing the lifetime yourself: for example, a struct that allocates memory
should generally free that memory in its deinitializer.
#### Wildcard origins
The wildcard origins, `ImmUnsafeAnyOrigin` and `MutUnsafeAnyOrigin`, are
special cases indicating a reference that might access any live value. These
were previously widely used for unsafe pointers. Using a pointer with a wildcard
origin into a scope effectively disables Mojo's ASAP destruction for any values
in that scope, as long as the pointer is live. It also prevents Mojo from
enforcing
[argument exclusivity](/docs/manual/values/ownership/#argument-exclusivity) and
hides unused variable warnings.
Accordingly, the use of wildcard origins is discouraged, and should be used as a
last resort.
## Working with references
You can use the `ref` keyword with arguments and return values to specify a
reference with parametric mutability. That is, they can be either mutable or
immutable.
A `ref` return value looks like any other return value to the calling function,
but it's a *reference* to an existing value, not a copy.
### `ref` arguments
The `ref` argument convention lets you specify an argument of parametric
mutability: that is, you don't need to know in advance whether the passed
argument will be mutable or immutable. There are several reasons you might want
to use a `ref` argument:
- You want to accept an argument with parametric mutability.
- You want to tie the lifetime of one argument to the lifetime of another
argument.
- When you want an argument that is guaranteed to be passed in memory: this
can be useful for parameterized arguments that need an identity, whether
or not the concrete type is register passable.
The syntax for a `ref` argument is:
<code><strong>ref</strong> <var>arg_name</var>: <var>arg_type</var></code>
Or:
<code><strong>ref[</strong><var>origin_specifier(s)</var><strong>] </strong>
<var>arg_name</var>: <var>arg_type</var></code>
In the first form, the origin and mutability of the `ref` argument is inferred
from the value passed in. The second form includes an origin clause, consisting
of one or more origin specifiers inside square brackets. An origin
specifier can be either:
- An origin value.
- An arbitrary expression, which is treated as shorthand for
`origin_of(expression)`. In other words, the following declarations are
equivalent:
```mojo
ref[origin_of(self)]
ref[self]
```
- An [`AddressSpace`](/docs/std/memory/address_space/AddressSpace/) value.
- An underscore character (`_`) to indicate that the origin is *unbound*. This
is equivalent to omitting the origin specifier.
```mojo
def add_ref(ref a: Int, b: Int) -> Int:
return a+b
```
You can also name the origin explicitly. This is useful if you want to
restrict the argument to either a `ImmOrigin` or `MutOrigin`, or if you
want to bind a function's return value to the origin of an argument.
For example, the `Span` type is a non-owning view of contiguous data (like
a substring of a string, or a subset of a list). Because it points to data
that it doesn't own, it is parameterized on an origin value that represents
the lifetime and ownership of the data it points to.
In the following example, the `to_byte_span()` function takes a
`List[Byte]` and returns a `Span[Byte]` with the same origin as the list:
```mojo
from std.collections import List, Span
def to_byte_span[
is_mutable: Bool,
//,
origin: Origin[mut=is_mutable],
](ref[origin] list: List[Byte]) -> Span[Byte, origin]:
return Span(list)
def main():
var list: List[Byte] = [77, 111, 106, 111]
_ = to_byte_span(list)
```
In this example, the `origin` parameter is inferred from the `list` argument,
and then used as the origin for the returned `Span`.
Since the `Span` takes on the origin of the `list` argument, the Mojo compiler
can identify the span's data as owned by the list. The span will have the same
lifetime as the list, and the span will be mutable if the list is mutable.
### `ref` return values
Like `ref` arguments, `ref` return values allow a function to return a mutable
or immutable reference to a value. The syntax for a `ref` return value is:
<code><strong>-> ref[</strong><var>origin_specifier(s)</var><strong>] </strong>
<var>arg_type</var></code>
Note that you **must** provide an origin specifier for a `ref` return value. The
values allowed for origin specifiers are the same as the ones listed for
[`ref` arguments](#ref-arguments).
`ref` return values can be an efficient way to handle updating items in a
collection. The standard way to do this is by implementing the `__getitem__()`
and `__setitem__()` dunder methods. These are invoked to read from and write to
a subscripted item in a collection:
```mojo
var value = list[a]
list[b] += 10
```
With a `ref` argument, `__getitem__()` can return a mutable reference that can
be modified directly. This has pros and cons compared to using a `__setitem__()`
method:
- The mutable reference is more efficient—a single update isn't broken up across
two methods. However, the referenced value must be in memory.
- A `__getitem__()`/`__setitem__()` pair allows for arbitrary code to be run
when values are retrieved and set. For example, `__setitem__()` can validate
or constrain input values.
For example, in the following example, `NameList` has a `__getitem__()` method
that returns a reference:
```mojo
struct NameList:
var names: List[String]
def __init__(out self, *names: String):
self.names = []
for name in names:
self.names.append(name)
def __getitem__(ref self, index: Int) raises -> ref[self.names[0]] String:
if (index >=0 and index < len(self.names)):
return self.names[index]
else:
raise Error("index out of bounds")
def main() raises:
var list = NameList("Thor", "Athena", "Dana", "Vrinda")
ref name = list[2]
print(name)
name += "?"
print(list[2])