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()