Skip to main content

/

Docs

Nightly
v24.5
Log in

Mojo struct

UnsafePointer

This is a pointer type that can point to any generic value that is movable.

Parameters​

  • ​T (AnyType): The type the pointer points to.
  • ​address_space (AddressSpace): The address space associated with the UnsafePointer allocated memory.
  • ​exclusive (Bool): The underlying memory allocation of the pointer is known only to be accessible through this pointer.
  • ​alignment (Int): The minimum alignment of this pointer known statically.

Aliases​

  • type = T: The underlying pointer type.

Fields​

  • ​address (pointer<!kgen.paramref<:trait<@stdlib::@builtin::@anytype::@AnyType> T>, #lit.struct.extract<:@stdlib::@builtin::@int::@Int #lit.struct.extract<:@stdlib::@memory::@reference::@AddressSpace address_space, "_value">, "value"> exclusive(#lit.struct.extract<:@stdlib::@builtin::@bool::@Bool exclusive, "value">)>): The underlying pointer.

Implemented traits​

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

Methods​

__init__​

__init__(inout self: Self)

Create a null pointer.

__init__(inout self: Self, value: pointer<!kgen.paramref<:trait<_stdlib::_builtin::_anytype::_AnyType> T>, #lit.struct.extract<:_stdlib::_builtin::_int::_Int #lit.struct.extract<:_stdlib::_memory::_reference::_AddressSpace address_space, "_value">, "value"> exclusive(#lit.struct.extract<:_stdlib::_builtin::_bool::_Bool exclusive, "value">)>)

Create a pointer with the input value.

Args:

  • ​value (pointer<!kgen.paramref<:trait<_stdlib::_builtin::_anytype::_AnyType> T>, #lit.struct.extract<:_stdlib::_builtin::_int::_Int #lit.struct.extract<:_stdlib::_memory::_reference::_AddressSpace address_space, "_value">, "value"> exclusive(#lit.struct.extract<:_stdlib::_builtin::_bool::_Bool exclusive, "value">)>): The MLIR value of the pointer to construct with.

__init__(inout self: Self, other: UnsafePointer[T, address_space, exclusive, alignment])

Exclusivity parameter cast a pointer.

Args:

  • ​other (UnsafePointer[T, address_space, exclusive, alignment]): Pointer to cast.

__init__(inout self: Self, *, other: Self)

Copy the object.

Args:

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

__bool__​

__bool__(self: Self) -> Bool

Return true if the pointer is non-null.

Returns:

Whether the pointer is null.

__getitem__​

__getitem__(self: Self) -> ref [MutableStaticLifetime, address_space] T

Return a reference to the underlying data.

Returns:

A reference to the value.

__getitem__[IntLike: IntLike, //](self: Self, offset: IntLike) -> ref [MutableStaticLifetime, address_space] T

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: 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: 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: 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: 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: 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: 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: 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: 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, //](inout self: 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, //](inout self: 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 [arg_is_lifetime, address_space] arg: T) -> Self

Gets the address of the argument.

Args:

  • ​arg (T): The value to get the address of.

Returns:

An UnsafePointer which contains the address of the argument.

alloc​

static alloc(count: Int) -> Self

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: 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: Self) -> Bool

Return true if the pointer is non-null.

Returns:

Whether the pointer is null.

__int__​

__int__(self: Self) -> Int

Returns the pointer address as an integer.

Returns:

The address of the pointer as an Int.

__str__​

__str__(self: Self) -> String

Gets a string representation of the pointer.

Returns:

The string representation of the pointer.

format_to​

format_to(self: Self, inout writer: Formatter)

Formats this pointer address to the provided formatter.

Args:

  • ​writer (Formatter): The formatter to write to.

load​

load[type: DType, //, width: Int = 1, *, alignment: Int = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment]) -> SIMD[$0, $1]

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.

Returns:

The loaded value.

load[type: DType, //, width: Int = 1, *, alignment: Int = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], offset: SIMD[type, 1]) -> SIMD[$0, $1]

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.

Args:

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

Returns:

The loaded value.

load[T: IntLike, type: DType, //, width: Int = 1, *, alignment: Int = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], offset: T) -> SIMD[$1, $2]

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.

Args:

  • ​offset (T): The offset to load from.

Returns:

The loaded value.

store​

store[T: IntLike, type: DType, //, width: Int = 1, *, alignment: Int = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], 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.

Args:

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

store[type: DType, //, width: Int = 1, *, alignment: Int = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], offset: SIMD[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.
  • ​alignment (Int): The minimal alignment of the address.

Args:

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

store[type: DType, //, width: Int = 1, *, alignment: Int = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], 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.

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, exclusive, alignment], stride: T) -> SIMD[$0, $2]

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, exclusive, alignment], 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 = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], offset: SIMD[type, width], mask: SIMD[bool, width] = 1, default: SIMD[type, width] = 0) -> SIMD[$0, $1]

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 = alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1](self: UnsafePointer[SIMD[type, 1], address_space, exclusive, alignment], offset: SIMD[type, width], val: SIMD[type, width], mask: SIMD[bool, width] = 1)

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: Self)

Free the memory referenced by the pointer.

bitcast​

bitcast[T: AnyType = T, /, address_space: AddressSpace = address_space](self: Self) -> UnsafePointer[$0, $1, 0, alignment]

Bitcasts a UnsafePointer to a different type.

Parameters:

  • ​T (AnyType): The target type.
  • ​address_space (AddressSpace): The address space of the result.

Returns:

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

bitcast[T: DType, /, address_space: AddressSpace = address_space](self: Self) -> UnsafePointer[SIMD[$0, 1], $1, 0, alignment]

Bitcasts a UnsafePointer to a different type.

Parameters:

  • ​T (DType): The target type.
  • ​address_space (AddressSpace): The address space of the result.

Returns:

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

destroy_pointee​

destroy_pointee(self: UnsafePointer[T, 0, 0, alignment])

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 T. 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, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1]) -> $0

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 lifetime 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, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1], 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, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1], value: T)

Emplace a copy of value into the pointer location.

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_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, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1], value: T)

Emplace a copy of value into this pointer location.

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_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, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1], dst: UnsafePointer[T, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1])

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, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1]): Destination pointer that the value will be moved into.