OwnedPointer

struct OwnedPointer[T: AnyType]

A safe, owning, smart pointer.

This smart pointer is designed for cases where there is clear ownership of the underlying data, and restricts access to it through the origin system such that no more than one mutable alias for the underlying data may exist.

For a comparison with other pointer types, see Intro to pointers in the Mojo Manual.

Parameters

• ​T (AnyType): The type to be stored in the OwnedPointer. When T is not Deinitable, the OwnedPointer has no implicit destructor and must be consumed with deinit_with() or into_inner() (for a Movable T).

Implemented traits

AnyType, Deinitable (where conforms_to(T, Deinitable)), Movable, RegisterPassable, UnsafeNicheable, Writable (where conforms_to(T, Writable)), _FieldNicheable

Methods

__init__

def __init__(var value: T, /) -> Self where conforms_to(T, Movable)

Construct a new OwnedPointer by moving the passed value into a new backing allocation.

Args:

• ​value (T): The value to move into the OwnedPointer.

def __init__(*, var init_with: T) -> Self

Construct a new OwnedPointer holding the value returned by init_with.

The value is constructed directly into the new backing allocation rather than being constructed elsewhere and then moved, so T does not need to be Movable.

from std.memory import OwnedPointer

@fieldwise_init
struct Pinned(not Movable):
    var value: Int

var ptr = OwnedPointer(init_with=lambda () -> Pinned: Pinned(7))
print(ptr[].value)  # => 7

Args:

• ​init_with (T): A function that constructs and returns the value to store in the OwnedPointer.

def __init__(*, copy_value: T) -> Self where conforms_to(T, Copyable)

Construct a new OwnedPointer by explicitly copying the passed value into a new backing allocation.

Deprecated: This OwnedPointer initializer is deprecated. Use the by value or in-place initializers.

Args:

• ​copy_value (T): The value to explicitly copy into the OwnedPointer.

def __init__[_T: Copyable, U: NoneType = None](value: _T) -> OwnedPointer[_T] where not conforms_to(_T, ImplicitlyCopyable).__bool__() where identical(T, _T)

Construct a new OwnedPointer by copying the passed value into a new backing allocation.

Deprecated: This OwnedPointer initializer is deprecated. Use the by value or in-place initializers.

Parameters:

• ​_T (Copyable): The type of the data to store.
• ​U (NoneType): A dummy type parameter, to lower the selection priority of this ctor.

Args:

• ​value (_T): The value to copy into the OwnedPointer.

Returns:

OwnedPointer[_T]

def __init__(*, other: Self) -> Self where conforms_to(T, Copyable)

Construct a new OwnedPointer by explicitly copying the value from another OwnedPointer.

Args:

• ​other (Self): The OwnedPointer to copy.

def __init__(*, unsafe_from_raw_pointer: Pointer[T, MutUntrackedOrigin]) -> Self

Construct a new OwnedPointer by taking ownership of the provided Pointer.

Safety:

This function is unsafe as the provided Pointer must be initialize with a single valid T initially allocated with this OwnedPointer's backing allocator. This function is unsafe as other memory problems can arise such as a double-free if this function is called twice with the same pointer or a user manually deallocates the same data.

After using this constructor, the Pointer is assumed to be owned by this OwnedPointer. In particular, the destructor method will call T.__deinit__ and dealloc.

Args:

• ​unsafe_from_raw_pointer (Pointer[T, MutUntrackedOrigin]): The Pointer to take ownership of.

def __init__(*, unsafe_from_opaque_pointer: MutOpaquePointer) -> Self

Construct a new OwnedPointer by taking ownership of the provided Pointer.

Safety:

This function is unsafe as the provided OpaquePointer must be initialize with a single valid T initially allocated with this OwnedPointer's backing allocator. This function is unsafe as other memory problems can arise such as a double-free if this function is called twice with the same pointer or a user manually deallocates the same data.

After using this constructor, the Pointer is assumed to be owned by this OwnedPointer. In particular, the destructor method will call T.__deinit__ and dealloc.

Args:

• ​unsafe_from_opaque_pointer (MutOpaquePointer): The OpaquePointer to take ownership of.

__deinit__

def __deinit__(deinit self) where conforms_to(T, Deinitable)

Destroy the OwnedPointer, running the destructor of its value.

Constraints:

T must be Deinitable. When it is not, the OwnedPointer has no implicit destructor and must be consumed with deinit_with() or into_inner() (for a Movable T).

__getitem__

def __getitem__(ref self) -> ref[self_is_mut["value"]] T

Returns a reference to the pointers's underlying data with parametric mutability.

Returns:

ref[self_is_mut["value"]] T: A reference to the data underlying the OwnedPointer.

deinit_with

def deinit_with(deinit self, deinit_func: T, /)

Consumes this OwnedPointer, passing its value to deinit_func to destroy it.

The value is destroyed in place in its backing allocation, so T does not need to be Movable or Deinitable.

Examples:

from std.memory import OwnedPointer

@fieldwise_init
struct Resource(not Deinitable, not Movable):
    var id: Int

    def close(deinit self):
        pass

var p = OwnedPointer(init_with=lambda () -> Resource: Resource(1))
p^.deinit_with(Resource.close)

Args:

• ​deinit_func (T): The function that takes ownership of the value to destroy it.

ptr

def ptr[origin: Origin[mut=origin.mut], //](ref[origin.mut] self) -> Pointer[T, origin]

Returns a pointer to the OwnedPointer's contents.

Parameters:

• ​origin (Origin[mut=mut]): The origin of the pointer.

Returns:

Pointer[T, origin]: A pointer to the OwnedPointer's contents.

into_inner

def into_inner(deinit self) -> T where conforms_to(T, Movable)

Move the value within the OwnedPointer out of it, consuming the OwnedPointer in the process.

Returns:

T: The data that is (was) backing the OwnedPointer.

unsafe_take_allocation

def unsafe_take_allocation(deinit self) -> Allocation[T]

Take ownership of the heap allocation backing this OwnedPointer.

Safety:

The pointee is handed over still initialized, and deallocating the storage does not run its destructor. Destroy it yourself before deallocating if T needs it.

The returned Allocation is an explicitly destroyed handle, so the compiler requires the caller to consume it: pass it to dealloc, or take the raw pointer with unsafe_leak().

Returns:

Allocation[T]: The Allocation that owns the backing storage.

write_to

def write_to(self, mut writer: T) where conforms_to(T, Writable)

Formats this pointer's value to the provided Writer.

Constraints:

T must conform to Writable.

Args:

• ​writer (T): The object to write to.

write_repr_to

def write_repr_to(self, mut writer: T) where conforms_to(T, Writable)

Write the string representation of the OwnedPointer.

Constraints:

T must conform to Writable.

Args:

• ​writer (T): The object to write to.