295 lines
10 KiB
Mojo
295 lines
10 KiB
Mojo
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()
|