Mojo struct

UnsafePointer

@register_passable(trivial) struct UnsafePointer[type: AnyType, *, address_space: AddressSpace = 0, alignment: Int = _default_alignment[::AnyType](), origin: MutableOrigin = MutableAnyOrigin]

UnsafePointer[T] represents an indirect reference to one or more values of type T consecutively in memory, and can refer to uninitialized memory.

Because it supports referring to uninitialized memory, it provides unsafe methods for initializing and destroying instances of T, as well as methods for accessing the values once they are initialized.

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

Parameters

type (AnyType): The type the pointer points to.
address_space (AddressSpace): The address space associated with the UnsafePointer allocated memory.
alignment (Int): The minimum alignment of this pointer known statically.
origin (MutableOrigin): The origin of the memory being addressed.

Fields

address (pointer<:trait<@stdlib::@builtin::@anytype::@AnyType> *"type", #lit.struct.extract<:@stdlib::@builtin::@int::@Int #lit.struct.extract<:@stdlib::@memory::@pointer::@AddressSpace address_space, "_value">, "value">>): The underlying pointer.

Implemented traits

AnyType, Boolable, CollectionElement, CollectionElementNew, Comparable, Copyable, EqualityComparable, ExplicitlyCopyable, ImplicitlyBoolable, Intable, Movable, Stringable, UnknownDestructibility, Writable

Methods

`init`

__init__(out self)

Create a null pointer.

__init__(out self, other: UnsafePointer[type, address_space=address_space, alignment=alignment, origin=origin])

Exclusivity parameter cast a pointer.

Args:

other (UnsafePointer[type, address_space=address_space, alignment=alignment, origin=origin]): Pointer to cast.

__init__(out self, *, other: Self)

Copy an existing pointer.

Args:

other (Self): The value to copy.

`bool`

__bool__(self) -> Bool

Return true if the pointer is non-null.

Returns:

Whether the pointer is null.

`getitem`

__getitem__(self) -> ref [origin, address_space] type

Return a reference to the underlying data.

Returns:

A reference to the value.

__getitem__[IntLike: IntLike, //](self, offset: IntLike) -> ref [origin, address_space] type

Return a reference to the underlying data, offset by the given index.

Parameters:

IntLike (IntLike): The type of idx; either Int or UInt.

Args:

offset (IntLike): The offset index.

Returns:

An offset reference.

`lt`

__lt__(self, rhs: Self) -> Bool

Returns True if this pointer represents a lower address than rhs.

Args:

rhs (Self): The value of the other pointer.

Returns:

True if this pointer represents a lower address and False otherwise.

`le`

__le__(self, rhs: Self) -> Bool

Returns True if this pointer represents a lower than or equal address than rhs.

Args:

rhs (Self): The value of the other pointer.

Returns:

True if this pointer represents a lower address and False otherwise.

`eq`

__eq__(self, rhs: Self) -> Bool

Returns True if the two pointers are equal.

Args:

rhs (Self): The value of the other pointer.

Returns:

True if the two pointers are equal and False otherwise.

`ne`

__ne__(self, rhs: Self) -> Bool

Returns True if the two pointers are not equal.

Args:

rhs (Self): The value of the other pointer.

Returns:

True if the two pointers are not equal and False otherwise.

`gt`

__gt__(self, rhs: Self) -> Bool

Returns True if this pointer represents a higher address than rhs.

Args:

rhs (Self): The value of the other pointer.

Returns:

True if this pointer represents a higher than or equal address and False otherwise.

`ge`

__ge__(self, rhs: Self) -> Bool

Returns True if this pointer represents a higher than or equal address than rhs.

Args:

rhs (Self): The value of the other pointer.

Returns:

True if this pointer represents a higher than or equal address and False otherwise.

`add`

__add__[T: IntLike, //](self, offset: T) -> Self

Return a pointer at an offset from the current one.

Parameters:

T (IntLike): The type of idx; either Int or UInt.

Args:

offset (T): The offset index.

Returns:

An offset pointer.

`sub`

__sub__[T: IntLike, //](self, offset: T) -> Self

Return a pointer at an offset from the current one.

Parameters:

T (IntLike): The type of idx; either Int or UInt.

Args:

offset (T): The offset index.

Returns:

An offset pointer.

`iadd`

__iadd__[T: IntLike, //](mut self, offset: T)

Add an offset to this pointer.

Parameters:

T (IntLike): The type of idx; either Int or UInt.

Args:

offset (T): The offset index.

`isub`

__isub__[T: IntLike, //](mut self, offset: T)

Subtract an offset from this pointer.

Parameters:

T (IntLike): The type of idx; either Int or UInt.

Args:

offset (T): The offset index.

`address_of`

static address_of(ref [address_space] arg: type) -> UnsafePointer[type, address_space=address_space, alignment=1]

Gets the address of the argument.

Args:

arg (type): The value to get the address of.

Returns:

An UnsafePointer which contains the address of the argument.

`alloc`

static alloc(count: Int) -> UnsafePointer[type, alignment=alignment]

Allocate an array with specified or default alignment.

Args:

count (Int): The number of elements in the array.

Returns:

The pointer to the newly allocated array.

`offset`

offset[T: IntLike, //](self, idx: T) -> Self

Returns a new pointer shifted by the specified offset.

Parameters:

T (IntLike): The type of idx; either Int or UInt.

Args:

idx (T): The offset of the new pointer.

Returns:

The new constructed UnsafePointer.

`__as_bool__`

__as_bool__(self) -> Bool

Return true if the pointer is non-null.

Returns:

Whether the pointer is null.

`int`

__int__(self) -> Int

Returns the pointer address as an integer.

Returns:

The address of the pointer as an Int.

`str`

__str__(self) -> String

Gets a string representation of the pointer.

Returns:

The string representation of the pointer.

`write_to`

write_to[W: Writer](self, mut writer: W)

Formats this pointer address to the provided Writer.

Parameters:

W (Writer): A type conforming to the Writable trait.

Args:

writer (W): The object to write to.

`as_noalias_ptr`

as_noalias_ptr(self) -> Self

Cast the pointer to a new pointer that is known not to locally alias any other pointer. In other words, the pointer transitively does not alias any other memory value declared in the local function context.

This information is relayed to the optimizer. If the pointer does locally alias another memory value, the behaviour is undefined.

Returns:

A noalias pointer.

`load`

load[type: DType, //, width: Int = 1, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False, invariant: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin]) -> SIMD[type, width]

Loads the value the pointer points to.

Constraints:

The width and alignment must be positive integer values.

Parameters:

type (DType): The data type of SIMD vector.
width (Int): The size of the SIMD vector.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.
invariant (Bool): Whether the memory is load invariant.

Returns:

The loaded value.

Loads the value the pointer points to with the given offset.

Constraints:

The width and alignment must be positive integer values. The offset must be integer.

Parameters:

type (DType): The data type of SIMD vector elements.
width (Int): The size of the SIMD vector.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.
invariant (Bool): Whether the memory is load invariant.

Args:

offset (SIMD[type, 1]): The offset to load from.

Returns:

The loaded value.

load[T: IntLike, type: DType, //, width: Int = 1, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False, invariant: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: T) -> SIMD[type, width]

Loads the value the pointer points to with the given offset.

Constraints:

The width and alignment must be positive integer values.

Parameters:

T (IntLike): The type of offset, either Int or UInt.
type (DType): The data type of SIMD vector elements.
width (Int): The size of the SIMD vector.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.
invariant (Bool): Whether the memory is load invariant.

Args:

offset (T): The offset to load from.

Returns:

The loaded value.

`store`

store[T: IntLike, type: DType, //, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: T, val: SIMD[type, 1])

Stores a single element value at the given offset.

Constraints:

The width and alignment must be positive integer values. The offset must be integer.

Parameters:

T (IntLike): The type of offset, either Int or UInt.
type (DType): The data type of SIMD vector elements.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.

Args:

offset (T): The offset to store to.
val (SIMD[type, 1]): The value to store.

store[T: IntLike, type: DType, width: Int, //, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: T, val: SIMD[type, width])

Stores a single element value at the given offset.

Constraints:

The width and alignment must be positive integer values. The offset must be integer.

Parameters:

T (IntLike): The type of offset, either Int or UInt.
type (DType): The data type of SIMD vector elements.
width (Int): The size of the SIMD vector.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.

Args:

offset (T): The offset to store to.
val (SIMD[type, width]): The value to store.

store[type: DType, offset_type: DType, //, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: SIMD[offset_type, 1], val: SIMD[type, 1])

Stores a single element value at the given offset.

Constraints:

The width and alignment must be positive integer values.

Parameters:

type (DType): The data type of SIMD vector elements.
offset_type (DType): The data type of the offset value.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.

Args:

offset (SIMD[offset_type, 1]): The offset to store to.
val (SIMD[type, 1]): The value to store.

store[type: DType, width: Int, offset_type: DType, //, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: SIMD[offset_type, 1], val: SIMD[type, width])

Stores a single element value at the given offset.

Constraints:

The width and alignment must be positive integer values.

Parameters:

type (DType): The data type of SIMD vector elements.
width (Int): The size of the SIMD vector.
offset_type (DType): The data type of the offset value.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.

Args:

offset (SIMD[offset_type, 1]): The offset to store to.
val (SIMD[type, width]): The value to store.

store[type: DType, //, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], val: SIMD[type, 1])

Stores a single element value.

Constraints:

The width and alignment must be positive integer values.

Parameters:

type (DType): The data type of SIMD vector elements.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.

Args:

val (SIMD[type, 1]): The value to store.

store[type: DType, width: Int, //, *, alignment: Int = _default_alignment[::DType,::Int](), volatile: Bool = False](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], val: SIMD[type, width])

Stores a single element value.

Constraints:

The width and alignment must be positive integer values.

Parameters:

type (DType): The data type of SIMD vector elements.
width (Int): The size of the SIMD vector.
alignment (Int): The minimal alignment of the address.
volatile (Bool): Whether the operation is volatile or not.

Args:

val (SIMD[type, width]): The value to store.

`strided_load`

strided_load[type: DType, T: Intable, //, width: Int](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], stride: T) -> SIMD[type, width]

Performs a strided load of the SIMD vector.

Parameters:

type (DType): DType of returned SIMD value.
T (Intable): The Intable type of the stride.
width (Int): The SIMD width.

Args:

stride (T): The stride between loads.

Returns:

A vector which is stride loaded.

`strided_store`

strided_store[type: DType, T: Intable, //, width: Int](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], val: SIMD[type, width], stride: T)

Performs a strided store of the SIMD vector.

Parameters:

type (DType): DType of val, the SIMD value to store.
T (Intable): The Intable type of the stride.
width (Int): The SIMD width.

Args:

val (SIMD[type, width]): The SIMD value to store.
stride (T): The stride between stores.

`gather`

gather[type: DType, //, *, width: Int = 1, alignment: Int = _default_alignment[::DType,::Int]()](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: SIMD[type, width], mask: SIMD[bool, width] = SIMD(True), default: SIMD[type, width] = SIMD(0)) -> SIMD[type, width]

Gathers a SIMD vector from offsets of the current pointer.

This method loads from memory addresses calculated by appropriately shifting the current pointer according to the offset SIMD vector, or takes from the default SIMD vector, depending on the values of the mask SIMD vector.

If a mask element is True, the respective result element is given by the current pointer and the offset SIMD vector; otherwise, the result element is taken from the default SIMD vector.

Constraints:

The offset type must be an integral type. The alignment must be a power of two integer value.

Parameters:

type (DType): DType of the return SIMD.
width (Int): The SIMD width.
alignment (Int): The minimal alignment of the address.

Args:

offset (SIMD[type, width]): The SIMD vector of offsets to gather from.
mask (SIMD[bool, width]): The SIMD vector of boolean values, indicating for each element whether to load from memory or to take from the default SIMD vector.
default (SIMD[type, width]): The SIMD vector providing default values to be taken where the mask SIMD vector is False.

Returns:

The SIMD vector containing the gathered values.

`scatter`

scatter[type: DType, //, *, width: Int = 1, alignment: Int = _default_alignment[::DType,::Int]()](self: UnsafePointer[SIMD[type, 1], address_space=address_space, alignment=alignment, origin=origin], offset: SIMD[type, width], val: SIMD[type, width], mask: SIMD[bool, width] = SIMD(True))

Scatters a SIMD vector into offsets of the current pointer.

This method stores at memory addresses calculated by appropriately shifting the current pointer according to the offset SIMD vector, depending on the values of the mask SIMD vector.

If a mask element is True, the respective element in the val SIMD vector is stored at the memory address defined by the current pointer and the offset SIMD vector; otherwise, no action is taken for that element in val.

If the same offset is targeted multiple times, the values are stored in the order they appear in the val SIMD vector, from the first to the last element.

Constraints:

The offset type must be an integral type. The alignment must be a power of two integer value.

Parameters:

type (DType): DType of value, the result SIMD buffer.
width (Int): The SIMD width.
alignment (Int): The minimal alignment of the address.

Args:

offset (SIMD[type, width]): The SIMD vector of offsets to scatter into.
val (SIMD[type, width]): The SIMD vector containing the values to be scattered.
mask (SIMD[bool, width]): The SIMD vector of boolean values, indicating for each element whether to store at memory or not.

`free`

free(self: UnsafePointer[type, alignment=alignment, origin=origin])

Free the memory referenced by the pointer.

`bitcast`

bitcast[T: AnyType = type, /, address_space: AddressSpace = address_space, alignment: Int = alignment, origin: MutableOrigin = origin](self) -> UnsafePointer[T, address_space=address_space, alignment=alignment, origin=origin]

Bitcasts a UnsafePointer to a different type.

Parameters:

T (AnyType): The target type.
address_space (AddressSpace): The address space of the result.
alignment (Int): Alignment of the destination pointer.
origin (MutableOrigin): Origin of the destination pointer.

Returns:

A new UnsafePointer object with the specified type and the same address, as the original UnsafePointer.

`destroy_pointee`

destroy_pointee(self: UnsafePointer[type, alignment=alignment, origin=origin])

Destroy the pointed-to value.

The pointer must not be null, and the pointer memory location is assumed to contain a valid initialized instance of type. This is equivalent to _ = self.take_pointee() but doesn't require Movable and is more efficient because it doesn't invoke __moveinit__.

`take_pointee`

take_pointee[T: Movable, //](self: UnsafePointer[T, alignment=alignment, origin=origin]) -> T

Move the value at the pointer out, leaving it uninitialized.

The pointer must not be null, and the pointer memory location is assumed to contain a valid initialized instance of T.

This performs a consuming move, ending the origin of the value stored in this pointer memory location. Subsequent reads of this pointer are not valid. If a new valid value is stored using init_pointee_move(), then reading from this pointer becomes valid again.

Parameters:

T (Movable): The type the pointer points to, which must be Movable.

Returns:

The value at the pointer.

`init_pointee_move`

init_pointee_move[T: Movable, //](self: UnsafePointer[T, alignment=alignment, origin=origin], owned value: T)

Emplace a new value into the pointer location, moving from value.

The pointer memory location is assumed to contain uninitialized data, and consequently the current contents of this pointer are not destructed before writing value. Similarly, ownership of value is logically transferred into the pointer location.

When compared to init_pointee_copy, this avoids an extra copy on the caller side when the value is an owned rvalue.

Parameters:

T (Movable): The type the pointer points to, which must be Movable.

Args:

value (T): The value to emplace.

`init_pointee_copy`

init_pointee_copy[T: Copyable, //](self: UnsafePointer[T, alignment=alignment, origin=origin], value: T)

Emplace a copy of value into the pointer location.

When compared to init_pointee_move, this avoids an extra move on the callee side when the value must be copied.

Parameters:

T (Copyable): The type the pointer points to, which must be Copyable.

Args:

value (T): The value to emplace.

`init_pointee_explicit_copy`

init_pointee_explicit_copy[T: ExplicitlyCopyable, //](self: UnsafePointer[T, alignment=alignment, origin=origin], value: T)

Emplace a copy of value into this pointer location.

When compared to init_pointee_move, this avoids an extra move on the callee side when the value must be copied.

Parameters:

T (ExplicitlyCopyable): The type the pointer points to, which must be ExplicitlyCopyable.

Args:

value (T): The value to emplace.

`move_pointee_into`

move_pointee_into[T: Movable, //](self: UnsafePointer[T, alignment=alignment, origin=origin], dst: UnsafePointer[T, alignment=alignment, origin=origin])

Moves the value self points to into the memory location pointed to by dst.

This performs a consuming move (using __moveinit__()) out of the memory location pointed to by self. Subsequent reads of this pointer are not valid unless and until a new, valid value has been moved into this pointer's memory location using init_pointee_move().

This transfers the value out of self and into dest using at most one __moveinit__() call.

Safety:

self must be non-null
self must contain a valid, initialized instance of T
dst must not be null
The contents of dst should be uninitialized. If dst was previously written with a valid value, that value will be be overwritten and its destructor will NOT be run.

Parameters:

T (Movable): The type the pointer points to, which must be Movable.

Args:

dst (UnsafePointer[T, alignment=alignment, origin=origin]): Destination pointer that the value will be moved into.

Parameters​

Fields​

Implemented traits​

Methods​

__init__​

__bool__​

__getitem__​

__lt__​

__le__​

__eq__​

__ne__​

__gt__​

__ge__​

__add__​

__sub__​

__iadd__​

__isub__​

address_of​

alloc​

offset​

__as_bool__​

__int__​

__str__​

write_to​

as_noalias_ptr​

load​

store​

strided_load​

strided_store​

gather​

scatter​

free​

bitcast​

destroy_pointee​

take_pointee​

init_pointee_move​

init_pointee_copy​

init_pointee_explicit_copy​

move_pointee_into​

Parameters

Fields

Implemented traits

Methods

`init`

`bool`

`getitem`

`lt`

`le`

`eq`

`ne`

`gt`

`ge`

`add`

`sub`

`iadd`

`isub`

`address_of`

`alloc`

`offset`

`__as_bool__`

`int`

`str`

`write_to`

`as_noalias_ptr`

`load`

`store`

`strided_load`

`strided_store`

`gather`

`scatter`

`free`

`bitcast`

`destroy_pointee`

`take_pointee`

`init_pointee_move`

`init_pointee_copy`

`init_pointee_explicit_copy`

`move_pointee_into`