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,294 @@
struct Pointer[
mut: Bool,
//,
T: AnyType,
origin: Origin[mut=mut],
*,
address_space: AddressSpace = .GENERIC,
]
```
For pointers initialized with the `to` keyword argument, the origin is inferred
from the origin of the pointee. For example, in the following code,
`s_ptr.origin` is the same as the origin of `s`:
```mojo
var s = "Testing"
var s_ptr = Pointer(to=s)
```
When allocating memory with the `alloc()` function, the returned pointer has an
`origin` value of `MutUntrackedOrigin`. This value represents an origin that is
mutable and doesn't *alias* existing values. For example, it doesn't point to
the memory allocated for any other variable. This memory isn't
tracked by Mojo's lifetime checker and you're responsible for freeing it.
If you're using a pointer in the implementation of a struct, you usually
don't have to worry about the origin, as long as the pointer isn't exposed
outside of the struct. For example, if you implement a static array type
that allocates memory in its initializer, deallocates in its deinitializer,
and doesn't expose the pointer outside of the struct, the default origin is
fine.
But if the struct exposes a pointer or reference to that memory, you need
to set the origin appropriately. For example, the
[`List`](/docs/std/collections/list/List/) type has an `unsafe_ptr()`
method that returns a `Pointer` to the underlying storage. In this case,
the returned pointer should share the origin of the list, since the list is
the logical owner of the storage.
That method looks something like this:
```mojo no-test
def unsafe_ptr[
origin: Origin, address_space: AddressSpace, //
](ref[origin, address_space] self) -> Pointer[
Self.T, origin, address_space=address_space
]:
return (
self._data.unsafe_mut_cast[origin.mut]()
.unsafe_origin_cast[origin]()
.unsafe_address_space_cast[address_space]()
)
```
This returns a copy of the original pointer, with the origin set to match the
origin and mutability of the `self` value.
A method like this is unsafe, but setting the correct origin makes it safer,
since the compiler knows that the pointer is referring to data owned by the
list.
When taking a pointer as a function argument, you often want to require either
a mutable or immutable origin, but otherwise allow the compiler to infer the
origin. Here's an example:
```mojo
def print_bytes(bytes: Pointer[mut=False, Byte, _], count: Int):
for i in range(count):
print(hex(bytes[unsafe_offset=i]), end=" ")
print()
```
By binding the infer-only `mut` parameter to `False`, and leaving the origin
unbound (using `_`), this signature lets the compiler infer the origin, but
forces the origin to be immutable. Mojo can implicitly cast a mutable pointer to
an immutable pointer, so you can pass a mutable pointer into `print_bytes()`,
but the function can't mutate the data.
## Working with nullability
`Pointer` is a non-nullable type. To model a null pointer, wrap it
in [`Optional`](/docs/std/collections/optional/Optional/):
```mojo
var ptr = Optional[Pointer[Int, MutUntrackedOrigin]]()
```
This creates an `Optional` with a value of `None`, which is equivalent
to a null pointer. `Optional[Pointer]` has the same memory layout
as a raw pointer, so you can pass it across FFI boundaries as `NULL`.
To check whether an optional pointer is null, use `Optional` methods:
```mojo
if ptr:
# ptr is not None — safe to unwrap
var p = ptr.value()
```
When you need a non-null value for deferred initialization, use
`unsafe_dangling()` instead of an `Optional`:
```mojo
var ptr = Pointer[Int, MutUntrackedOrigin].unsafe_dangling()
```
For a practical example of optional pointers in a data structure, see
[Self-referential structs](/docs/manual/structs/reference/).
## More memory allocation patterns
In some cases, you may not want to hold on to an `Allocation`:
- When allocating data for a struct, you may want to use a
[`ThinAllocation`](/docs/std/memory/alloc/ThinAllocation/) instead, to avoid
using extra memory.
- When working with raising functions, you sometimes need to avoid
an explicitly-destroyed type like `Allocation` or `ThinAllocation`.
The following sections describe these special cases.
### Holding an allocation in a struct field
When storing an allocation as a struct field, you may not want to store the
extra layout data included in the `Allocation` struct. The layout data is two
`Int` values (alignment and element count), typically an extra 16 bytes per
allocation. If your struct already tracks the amount of space it's allocated,
you can eliminate this extra space by storing a `ThinAllocation`, which is an
explicitly-destroyed wrapper around a pointer.
The `Allocation.into_thin()` method consumes the original allocation and
returns a `ThinAllocation`:
```mojo
struct Counter:
comptime _layout = Layout[Int].single()
var _alloc: ThinAllocation[Int]
def __init__(out self, value: Int):
self._alloc = alloc(Self._layout).into_thin()
self._alloc.unsafe_ptr().unsafe_write(value)
def increment(mut self):
self._alloc.unsafe_ptr()[] += 1
def get(self) -> Int:
return self._alloc.unsafe_ptr()[]
def __deinit__(deinit self):
# Convert ThinAllocation back into Allocation
dealloc(self._alloc^.unsafe_with_layout(Self._layout))
```
To deallocate a `ThinAllocation`, you need to supply the original layout
to reconstruct an `Allocation` using the `unsafe_with_layout()` method.
This example shows storing the layout as a comptime member; for a struct
with a dynamic size, you can reconstruct the original layout:
```mojo no-test
self._alloc^.unsafe_with_layout({count = size})
```
### Allocations and raising functions
Because `Allocation` and `ThinAllocation` need to be explicitly deallocated
before they go out of scope, they can conflict with raising functions.
Consider the following code:
```mojo no-test
def allocating_function() raises:
var data = alloc[Float64]({count = 64})
# ...
raising_function(data.unsafe_ptr())
dealloc(data^)
```
Because an error can cause `allocating_function()` to exit without executing the
`dealloc()` call, the compiler identifies this as a potential memory leak. There
are a couple of approaches to this problem. The function can use a
`try`/`except` statement to ensure that the memory is deallocated in the event
of an error:
```mojo
def allocating_function() raises:
var data = alloc[Float64]({count = 64})
# ...
try:
raising_function(data.unsafe_ptr())
except e:
dealloc(data^)
raise e^ # propagate the error
dealloc(data^)
```
Where this isn't viable, the alternative is to use the
`unsafe_leak()` method to take ownership of the allocation's
pointer. This consumes the allocation, but requires you to
ensure the memory is deallocated. You should consider this
pattern a last resort if other patterns don't work:
```mojo
def leaky_function() raises:
var data_ptr = alloc[Float64]({count = 64}).unsafe_leak()
# ...
raising_function(data_ptr)
dealloc(
ThinAllocation(unsafe_owned_ptr=data_ptr).unsafe_with_layout(
{count = 64}
)
)
```
Downsides of this approach include:
- If `raising_function()` raises an error in this example, `dealloc()` never
gets called, leaking the memory.
- When you reconstruct an `Allocation` from a `Pointer` like this, you run the
risk of freeing the same memory twice.
## Working with foreign pointers
When exchanging data with other programming languages, you may need to construct
a `Pointer` from a foreign pointer. Mojo restricts creating
`Pointer` instances from arbitrary addresses, to avoid users accidentally
creating pointers that *alias* each other (that is, two pointers that refer to
the same location). However, there are specific methods you can use to get a
`Pointer` from a Python or C/C++ pointer.
When dealing with memory allocated elsewhere, you need to be aware of who's
responsible for freeing the memory. Freeing memory allocated elsewhere
can result in undefined behavior.
When working with some foreign functions, you may need to supply a pointer with
no specific type (a type-erased pointer, or "void pointer" in C/C++). This is
equivalent to a Mojo `OpaquePointer`.
You also need to be aware of the format of the data stored in memory, including
data types and byte order. For more information, see
[Converting data: bitcasting and byte order](#converting-data-bitcasting-and-byte-order).
### Creating a Mojo pointer from a raw memory address
You can create a `Pointer` from a raw memory address using the
`unsafe_from_address` initializer.
```mojo
def write_to_address(mmio_address: Int, value: Int32):
var ptr = Pointer[Int32, MutUntrackedOrigin](
unsafe_from_address=mmio_address
)
# Writing to a raw memory address may require a volatile load/store as the
# operation may have side effects not visible to the compiler.
# You can specify this using the `volatile` parameter.
ptr.unsafe_store[volatile=True](value)
```
This is unsafe, as the caller must ensure the address is valid before writing to
it, and that the memory is initialized before reading from it. The caller must
also ensure the pointer's origin and mutability are valid for the address;
failure to do so may result in undefined behavior.
### Creating a Mojo pointer from a Python pointer
The `PythonObject` type defines an
[`unsafe_get_as_pointer()`](/docs/std/python/python_object/PythonObject/#unsafe_get_as_pointer)
method to construct a `Pointer` from a Python address.
:::note
Where possible, use safer methods to exchange data with Python, such as the
[`python.numpy`](/docs/std/python/numpy/) module, which provides convenience
functions for transferring 1D NumPy arrays between Mojo and Python.
:::
The following code creates a NumPy array and then accesses the data
using a Mojo pointer:
```mojo
from std.python import Python
def share_array() raises:
var np = Python.import_module("numpy")
var arr = np.array(Python.list(1, 2, 3, 4, 5, 6, 7, 8, 9))
var ptr = arr.ctypes.data.unsafe_get_as_pointer[.int64]()
for i in range(9):
print(ptr[unsafe_offset=i], end=", ")
print()
def main() raises:
share_array()