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