Baseline: tree as shared
This commit is contained in:
commit
659c03bbf8
1471 files changed
+990535
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])
|
||||
Reference in new issue
Block a user