IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /docs/manual/basics.md). For the complete Mojo documentation index, see llms.txt.
Skip to main content
Version: Nightly
For the complete Mojo documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md).

UnsafeNullablePointer

struct UnsafeNullablePointer[mut: Bool, //, type: AnyType, origin: Origin[mut=mut], *, address_space: AddressSpace = AddressSpace.GENERIC]

A temporary UnsafeNullablePointer type used to help transition users of UnsafePointer to Optional[UnsafePointer] for explicit nullability.

Parameters

  • mut (Bool): Whether the origin is mutable.
  • type (AnyType): The type the pointer points to.
  • origin (Origin[mut=mut]): The origin of the memory being addressed.
  • address_space (AddressSpace): The address space associated with the pointer's allocated memory.

Fields

  • address (__mlir_type.`!kgen.pointer<:trait<@std::@builtin::@anytype::@AnyType> *"type", #lit.struct.extract<:!lit.struct<@std::@builtin::@int::@Int> #lit.struct.extract<:!lit.struct<@std::@memory::@pointer::@AddressSpace> address_space, "_value">, "_mlir_value">>`): The underlying pointer.

Implemented traits

AnyType, Boolable, Comparable, Copyable, Defaultable, DevicePassable, Equatable, ImplicitlyCopyable, ImplicitlyDestructible, Intable, Movable, RegisterPassable, TrivialRegisterPassable, Writable

comptime members

device_type

comptime device_type = UnsafeNullablePointer[type, origin, address_space=address_space]

DeviceBuffer dtypes are remapped to UnsafeNullablePointer when passed to accelerator devices.

Methods

__init__

def __init__() -> Self

Create a null pointer.

def __init__(*, unsafe_from_address: Int) -> Self

Create a pointer from a raw address.

Safety: Creating a pointer from a raw address is inherently 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 is valid for the address, failure to do may result in undefined behavior.

Args:

  • unsafe_from_address (Int): The raw address to create a pointer from.

def __init__(*, ref[origin, address_space] to: type) -> Self

Constructs a Pointer from a reference to a value.

Args:

  • to (type): The value to construct a pointer to.

@implicit def __init__[disambig2: Int = 0](other: UnsafeNullablePointer[address_space=other.address_space]) -> UnsafeNullablePointer[other.type, origin_of(other.origin), address_space=other.address_space]

Implicitly casts a mutable pointer to immutable.

Parameters:

  • disambig2 (Int): Ignored. Works around name mangling conflict.

Args:

Returns:

UnsafeNullablePointer[other.type, origin_of(other.origin), address_space=other.address_space]

@implicit def __init__[disambig: Int = 0](other: UnsafeNullablePointer[address_space=other.address_space]) -> UnsafeNullablePointer[other.type, MutAnyOrigin, address_space=other.address_space]

Implicitly casts a mutable pointer to MutAnyOrigin.

Parameters:

  • disambig (Int): Ignored. Works around name mangling conflict.

Args:

Returns:

UnsafeNullablePointer[other.type, MutAnyOrigin, address_space=other.address_space]

@implicit def __init__(other: UnsafeNullablePointer[address_space=other.address_space]) -> UnsafeNullablePointer[other.type, ImmutAnyOrigin, address_space=other.address_space]

Implicitly casts a pointer to ImmutAnyOrigin.

Args:

Returns:

UnsafeNullablePointer[other.type, ImmutAnyOrigin, address_space=other.address_space]

@implicit def __init__(other: UnsafePointer[address_space=other.address_space]) -> UnsafeNullablePointer[other.type, other.origin, address_space=other.address_space]

Implicitly casts an UnsafePointer to UnsafeNullablePointer.

Args:

Returns:

UnsafeNullablePointer[other.type, other.origin, address_space=other.address_space]

@implicit def __init__[disambig2: Int = 0](other: UnsafePointer[address_space=other.address_space]) -> UnsafeNullablePointer[other.type, origin_of(other.origin), address_space=other.address_space]

Implicitly casts an UnsafePointer to UnsafeNullablePointer.

Parameters:

  • disambig2 (Int): Ignored. Works around name mangling conflict.

Args:

Returns:

UnsafeNullablePointer[other.type, origin_of(other.origin), address_space=other.address_space]

@implicit def __init__[disambig: Int = 0](other: UnsafePointer[address_space=other.address_space]) -> UnsafeNullablePointer[other.type, MutAnyOrigin, address_space=other.address_space]

Implicitly casts an UnsafePointer to UnsafeNullablePointer.

Parameters:

  • disambig (Int): Ignored. Works around name mangling conflict.

Args:

Returns:

UnsafeNullablePointer[other.type, MutAnyOrigin, address_space=other.address_space]

@implicit def __init__[T: AnyType, other_origin: Origin[mut=other_origin.mut], other_address_space: AddressSpace, //](other: UnsafePointer[T, other_origin, address_space=other_address_space]) -> UnsafeNullablePointer[T, ImmutAnyOrigin, address_space=other_address_space]

Implicitly casts an UnsafePointer to UnsafeNullablePointer.

Args:

Returns:

UnsafeNullablePointer[T, ImmutAnyOrigin, address_space=other_address_space]

def __init__[T: ImplicitlyDestructible, //](*, ref[origin] unchecked_downcast_value: PythonObject) -> UnsafeNullablePointer[T, origin]

Downcast a PythonObject known to contain a Mojo object to a pointer.

This operation is only valid if the provided Python object contains an initialized Mojo object of matching type.

Parameters:

  • T (ImplicitlyDestructible): Pointee type that can be destroyed implicitly (without deinitializer arguments).

Args:

  • unchecked_downcast_value (PythonObject): The Python object to downcast from.

Returns:

UnsafeNullablePointer[T, origin]

__bool__

def __bool__(self) -> Bool

Return true if the pointer is non-null.

Returns:

Bool: Whether the pointer is null.

__getitem__

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

Please refer to UnsafePointer.__getitem__.

Returns:

ref[origin, address_space] type: A reference to the value.

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

Please refer to UnsafePointer.__getitem__.

Parameters:

  • I (Indexer): A type that can be used as an index.

Args:

  • offset (I): The offset index.

Returns:

ref[origin, address_space] type: An offset reference.

__lt__

def __lt__(self, rhs: UnsafeNullablePointer[type, address_space=address_space]) -> Bool

Please refer to UnsafePointer.__lt__.

Args:

Returns:

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

def __lt__(self, rhs: Self) -> Bool

Please refer to UnsafePointer.__lt__.

Args:

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

Returns:

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

__le__

def __le__(self, rhs: UnsafeNullablePointer[type, address_space=address_space]) -> Bool

Please refer to UnsafePointer.__le__.

Args:

Returns:

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

def __le__(self, rhs: Self) -> Bool

Please refer to UnsafePointer.__le__.

Args:

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

Returns:

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

__eq__

def __eq__(self, rhs: UnsafeNullablePointer[type, address_space=address_space]) -> Bool

Please refer to UnsafePointer.__eq__.

Args:

Returns:

Bool: True if the two pointers are equal and False otherwise.

def __eq__(self, rhs: Self) -> Bool

Please refer to UnsafePointer.__eq__.

Args:

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

Returns:

Bool: True if the two pointers are equal and False otherwise.

__ne__

def __ne__(self, rhs: UnsafeNullablePointer[type, address_space=address_space]) -> Bool

Please refer to UnsafePointer.__ne__.

Args:

Returns:

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

def __ne__(self, rhs: Self) -> Bool

Please refer to UnsafePointer.__ne__.

Args:

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

Returns:

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

__gt__

def __gt__(self, rhs: UnsafeNullablePointer[type, address_space=address_space]) -> Bool

Please refer to UnsafePointer.__gt__.

Args:

Returns:

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

def __gt__(self, rhs: Self) -> Bool

Please refer to UnsafePointer.__gt__.

Args:

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

Returns:

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

__ge__

def __ge__(self, rhs: UnsafeNullablePointer[type, address_space=address_space]) -> Bool

Please refer to UnsafePointer.__ge__.

Args:

Returns:

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

def __ge__(self, rhs: Self) -> Bool

Please refer to UnsafePointer.__ge__.

Args:

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

Returns:

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

__add__

def __add__[I: Indexer, //](self, offset: I) -> Self

Please refer to UnsafePointer.__add__.

Parameters:

  • I (Indexer): A type that can be used as an index.

Args:

  • offset (I): The offset index.

Returns:

Self: An offset pointer.

__sub__

def __sub__[I: Indexer, //](self, offset: I) -> Self

Please refer to UnsafePointer.__sub__.

Parameters:

  • I (Indexer): A type that can be used as an index.

Args:

  • offset (I): The offset index.

Returns:

Self: An offset pointer.

__iadd__

def __iadd__[I: Indexer, //](mut self, offset: I)

Please refer to UnsafePointer.__iadd__.

Parameters:

  • I (Indexer): A type that can be used as an index.

Args:

  • offset (I): The offset index.

__isub__

def __isub__[I: Indexer, //](mut self, offset: I)

Please refer to UnsafePointer.__isub__.

Parameters:

  • I (Indexer): A type that can be used as an index.

Args:

  • offset (I): The offset index.

to_unsafe_pointer_unchecked

def to_unsafe_pointer_unchecked(self) -> UnsafePointer[type, origin, address_space=address_space]

Transforms the UnsafeNullablePointer into a non-null UnsfaePointer.

This method does not check if self is null or not, that is up to the user.

Returns:

UnsafePointer[type, origin, address_space=address_space]: An UnsafePointer pointer to the same value as self.

__merge_with__

def __merge_with__[other_type: AnyStruct[UnsafeNullablePointer[type, other_type.origin, address_space=address_space]]](self) -> UnsafeNullablePointer[type, origin_of(origin, other_type.origin), address_space=address_space]

Please refer to UnsafePointer.__merge_with__.

Parameters:

  • other_type (AnyStruct[UnsafeNullablePointer[type, other_type.origin, address_space=address_space]]): The type of the pointer to merge with.

Returns:

UnsafeNullablePointer[type, origin_of(origin, other_type.origin), address_space=address_space]: A pointer merged with the specified other_type.

__int__

def __int__(self) -> Int

Please refer to UnsafePointer.__int__.

Returns:

Int: The address of the pointer as an Int.

write_to

def write_to(self, mut writer: T)

Please refer to UnsafePointer.write_to.

Args:

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

write_repr_to

def write_repr_to(self, mut writer: T)

Write the string representation of the UnsafeNullablePointer.

Args:

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

get_type_name

static def get_type_name() -> String

Gets this type name, for use in error messages when handing arguments to kernels. TODO: This will go away soon, when we get better error messages for kernel calls.

Returns:

String: This name of the type.

swap_pointees

def swap_pointees[U: Movable](self: UnsafeNullablePointer[U], other: UnsafeNullablePointer[U])

Please refer to UnsafePointer.swap_pointees.

Parameters:

  • U (Movable): The type the pointers point to, which must be Movable.

Args:

as_noalias_ptr

def as_noalias_ptr(self) -> Self

Please refer to UnsafePointer.as_noalias_ptr.

Returns:

Self: A noalias pointer.

load

def load[dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, invariant: Bool = _default_invariant[mut](), non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space]) -> SIMD[dtype, width]

Please refer to UnsafePointer.load.

Parameters:

  • dtype (DType): The data type of the SIMD vector.
  • width (Int): The number of elements to load.
  • alignment (Int): The minimal alignment (bytes) of the address.
  • volatile (Bool): Whether the operation is volatile.
  • invariant (Bool): Whether the load is from invariant memory.
  • non_temporal (Bool): Whether the load has no temporal locality (streaming).

Returns:

SIMD[dtype, width]: The loaded SIMD vector.

def load[dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, invariant: Bool = _default_invariant[mut](), non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], offset: Scalar) -> SIMD[dtype, width]

Please refer to UnsafePointer.load.

Parameters:

  • dtype (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.
  • non_temporal (Bool): Whether the load has no temporal locality (streaming).

Args:

  • offset (Scalar): The offset to load from.

Returns:

SIMD[dtype, width]: The loaded value.

def load[I: Indexer, dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, invariant: Bool = _default_invariant[mut](), non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], offset: I) -> SIMD[dtype, width]

Please refer to UnsafePointer.load.

Parameters:

  • I (Indexer): A type that can be used as an index.
  • dtype (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.
  • non_temporal (Bool): Whether the load has no temporal locality (streaming).

Args:

  • offset (I): The offset to load from.

Returns:

SIMD[dtype, width]: The loaded value.

store

def store[I: Indexer, dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], offset: I, val: SIMD[dtype, width])

Please refer to UnsafePointer.store.

Parameters:

  • I (Indexer): A type that can be used as an index.
  • dtype (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.
  • non_temporal (Bool): Whether the store has no temporal locality (streaming).

Args:

def store[dtype: DType, offset_type: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], offset: Scalar[offset_type], val: SIMD[dtype, width])

Please refer to UnsafePointer.store.

Parameters:

  • dtype (DType): The data type of SIMD vector elements.
  • offset_type (DType): The data type of the offset value.
  • 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.
  • non_temporal (Bool): Whether the store has no temporal locality (streaming).

Args:

def store[dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], val: SIMD[dtype, width])

Please refer to UnsafePointer.store.

Parameters:

  • dtype (DType): The data type of SIMD vector elements.
  • width (Int): The number of elements to store.
  • alignment (Int): The minimal alignment (bytes) of the address.
  • volatile (Bool): Whether the operation is volatile.
  • non_temporal (Bool): Whether the store has no temporal locality (streaming).

Args:

strided_load

def strided_load[dtype: DType, T: Intable, //, width: Int](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], stride: T) -> SIMD[dtype, width]

Please refer to UnsafePointer.strided_load.

Parameters:

  • dtype (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:

SIMD[dtype, width]: A vector which is stride loaded.

strided_store

def strided_store[dtype: DType, T: Intable, //, width: Int = 1](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], val: SIMD[dtype, width], stride: T)

Please refer to UnsafePointer.strided_store.

Parameters:

  • dtype (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[dtype, width]): The SIMD value to store.
  • stride (T): The stride between stores.

gather

def gather[dtype: DType, //, *, width: Int = 1, alignment: Int = align_of[dtype]()](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], offset: SIMD[width], mask: SIMD[DType.bool, width] = SIMD(fill=True), default: SIMD[dtype, width] = 0) -> SIMD[dtype, width]

Please refer to UnsafePointer.gather.

Parameters:

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

Args:

  • offset (SIMD[width]): The SIMD vector of offsets to gather from.
  • mask (SIMD[DType.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[dtype, width]): The SIMD vector providing default values to be taken where the mask SIMD vector is False.

Returns:

SIMD[dtype, width]: The SIMD vector containing the gathered values.

scatter

def scatter[dtype: DType, //, *, width: Int = 1, alignment: Int = align_of[dtype]()](self: UnsafeNullablePointer[Scalar[dtype], address_space=self.address_space], offset: SIMD[width], val: SIMD[dtype, width], mask: SIMD[DType.bool, width] = SIMD(fill=True))

Please refer to UnsafePointer.scatter.

Parameters:

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

Args:

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

free

def free(self: UnsafeNullablePointer[type, address_space=self.address_space])

Please refer to UnsafePointer.free.

bitcast

def bitcast[T: AnyType](self) -> UnsafeNullablePointer[T, origin, address_space=address_space]

Please refer to UnsafePointer.bitcast.

Parameters:

Returns:

UnsafeNullablePointer[T, origin, address_space=address_space]: A new UnsafeNullablePointer object with the specified type and the same address, as the original UnsafeNullablePointer.

mut_cast

def mut_cast[target_mut: Bool](self) -> UnsafeNullablePointer[type, origin_of(origin), address_space=address_space]

Please refer to UnsafePointer.mut_cast.

Parameters:

  • target_mut (Bool): Mutability of the destination pointer.

Returns:

UnsafeNullablePointer[type, origin_of(origin), address_space=address_space]: A pointer with the same type, origin and address space as the original pointer, but with the newly specified mutability.

unsafe_mut_cast

def unsafe_mut_cast[target_mut: Bool](self) -> UnsafeNullablePointer[type, origin_of(origin), address_space=address_space]

Please refer to UnsafePointer.unsafe_mut_cast.

Parameters:

  • target_mut (Bool): Mutability of the destination pointer.

Returns:

UnsafeNullablePointer[type, origin_of(origin), address_space=address_space]: A pointer with the same type, origin and address space as the original pointer, but with the newly specified mutability.

unsafe_origin_cast

def unsafe_origin_cast[target_origin: Origin[mut=mut]](self) -> UnsafeNullablePointer[type, target_origin, address_space=address_space]

Please refer to UnsafePointer.unsafe_origin_cast.

Parameters:

Returns:

UnsafeNullablePointer[type, target_origin, address_space=address_space]: A pointer with the same type, mutability and address space as the original pointer, but with the newly specified origin.

as_immutable

def as_immutable(self) -> UnsafeNullablePointer[type, origin_of(origin), address_space=address_space]

Please refer to UnsafePointer.as_immutable.

Returns:

UnsafeNullablePointer[type, origin_of(origin), address_space=address_space]: A pointer with the mutability set to immutable.

as_any_origin

def as_any_origin(self) -> UnsafeNullablePointer[type, AnyOrigin[mut=mut], address_space=address_space]

Please refer to UnsafePointer.as_any_origin.

Returns:

UnsafeNullablePointer[type, AnyOrigin[mut=mut], address_space=address_space]: A pointer with the origin set to AnyOrigin.

address_space_cast

def address_space_cast[target_address_space: AddressSpace = address_space](self) -> UnsafeNullablePointer[type, origin, address_space=target_address_space]

Please refer to UnsafePointer.address_space_cast.

Parameters:

  • target_address_space (AddressSpace): The address space of the result.

Returns:

UnsafeNullablePointer[type, origin, address_space=target_address_space]: A new UnsafeNullablePointer object with the same type and the same address, as the original UnsafeNullablePointer and the new address space.

destroy_pointee

def destroy_pointee[T: ImplicitlyDestructible, //](self: UnsafeNullablePointer[T]) where self.origin.mut

Please refer to UnsafePointer.destroy_pointee.

Parameters:

  • T (ImplicitlyDestructible): Pointee type that can be destroyed implicitly (without deinitializer arguments).

destroy_pointee_with

def destroy_pointee_with(self: UnsafeNullablePointer[type], destroy_func: def(var type) -> None) where self.origin.mut

Please refer to UnsafePointer.destroy_pointee_with.

Args:

  • destroy_func (def(var type) -> None): A function that takes ownership of the pointee value for the purpose of deinitializing it.

take_pointee

def take_pointee[T: Movable, //](self: UnsafeNullablePointer[T]) -> T where self.origin.mut

Please refer to UnsafePointer.take_pointee.

Parameters:

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

Returns:

T: The value at the pointer.

init_pointee_move

def init_pointee_move[T: Movable, //](self: UnsafeNullablePointer[T], var value: T) where self.origin.mut

Please refer to UnsafePointer.init_pointee_move.

Parameters:

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

Args:

  • value (T): The value to emplace.

init_pointee_copy

def init_pointee_copy[T: Copyable, //](self: UnsafeNullablePointer[T], value: T) where self.origin.mut

Please refer to UnsafePointer.init_pointee_copy.

Parameters:

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

Args:

  • value (T): The value to emplace.

init_pointee_move_from

def init_pointee_move_from[T: Movable, //](self: UnsafeNullablePointer[T], src: UnsafeNullablePointer[T]) where self.origin.mut and src.origin.mut

Please refer to UnsafePointer.init_pointee_move_from.

Parameters:

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

Args: