Skip to main content

/

DocsCode

Mojo struct

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): 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__​

__init__() -> Self

Create a null pointer.

__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.

__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 __init__[disambig2: Int = 0](other: UnsafeNullablePointer[other.type, other.origin, 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

@implicit __init__[disambig: Int = 0](other: UnsafeNullablePointer[other.type, other.origin, 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

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

Implicitly casts a pointer to ImmutAnyOrigin.

Args:

Returns:

UnsafeNullablePointer

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

Implicitly casts an UnsafePointer to UnsafeNullablePointer.

Args:

Returns:

UnsafeNullablePointer

@implicit __init__[disambig2: Int = 0](other: UnsafePointer[other.type, other.origin, 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

@implicit __init__[disambig: Int = 0](other: UnsafePointer[other.type, other.origin, 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

@implicit __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

__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

__bool__​

__bool__(self) -> Bool

Return true if the pointer is non-null.

Returns:

Bool: Whether the pointer is null.

__getitem__​

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

Please refer to UnsafePointer.__getitem__.

Returns:

ref: A reference to the value.

__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: An offset reference.

__lt__​

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

Please refer to UnsafePointer.__lt__.

Args:

Returns:

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

__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__​

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

Please refer to UnsafePointer.__le__.

Args:

Returns:

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

__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__​

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

Please refer to UnsafePointer.__eq__.

Args:

Returns:

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

__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__​

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

Please refer to UnsafePointer.__ne__.

Args:

Returns:

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

__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__​

__gt__(self, rhs: UnsafeNullablePointer[type, rhs.origin, 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.

__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__​

__ge__(self, rhs: UnsafeNullablePointer[type, rhs.origin, 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.

__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__​

__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__​

__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__​

__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__​

__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​

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: An UnsafePointer pointer to the same value as self.

__merge_with__​

__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): The type of the pointer to merge with.

Returns:

UnsafeNullablePointer: A pointer merged with the specified other_type.

__int__​

__int__(self) -> Int

Please refer to UnsafePointer.__int__.

Returns:

Int: The address of the pointer as an Int.

write_to​

write_to(self, mut writer: T)

Please refer to UnsafePointer.write_to.

Args:

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

write_repr_to​

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 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​

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

Please refer to UnsafePointer.swap_pointees.

Parameters:

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

Args:

as_noalias_ptr​

as_noalias_ptr(self) -> Self

Please refer to UnsafePointer.as_noalias_ptr.

Returns:

Self: A noalias pointer.

load​

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], self.origin, 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: The loaded SIMD vector.

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], self.origin, address_space=self.address_space], offset: Scalar[offset.dtype]) -> 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: The loaded value.

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], self.origin, 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: The loaded value.

store​

store[I: Indexer, dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], self.origin, 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:

  • ​offset (I): The offset to store to.
  • ​val (SIMD): The value to store.

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], self.origin, 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:

  • ​offset (Scalar): The offset to store to.
  • ​val (SIMD): The value to store.

store[dtype: DType, //, width: Int = 1, *, alignment: Int = align_of[dtype](), volatile: Bool = False, non_temporal: Bool = False](self: UnsafeNullablePointer[Scalar[dtype], self.origin, 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:

  • ​val (SIMD): The SIMD value to store.

strided_load​

strided_load[dtype: DType, T: Intable, //, width: Int](self: UnsafeNullablePointer[Scalar[dtype], self.origin, 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: A vector which is stride loaded.

strided_store​

strided_store[dtype: DType, T: Intable, //, width: Int = 1](self: UnsafeNullablePointer[Scalar[dtype], self.origin, 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): The SIMD value to store.
  • ​stride (T): The stride between stores.

gather​

gather[dtype: DType, //, *, width: Int = 1, alignment: Int = align_of[dtype]()](self: UnsafeNullablePointer[Scalar[dtype], self.origin, address_space=self.address_space], offset: SIMD[offset.dtype, 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): The SIMD vector of offsets to gather from.
  • ​mask (SIMD): 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): The SIMD vector providing default values to be taken where the mask SIMD vector is False.

Returns:

SIMD: The SIMD vector containing the gathered values.

scatter​

scatter[dtype: DType, //, *, width: Int = 1, alignment: Int = align_of[dtype]()](self: UnsafeNullablePointer[Scalar[dtype], self.origin, address_space=self.address_space], offset: SIMD[offset.dtype, 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): The SIMD vector of offsets to scatter into.
  • ​val (SIMD): The SIMD vector containing the values to be scattered.
  • ​mask (SIMD): The SIMD vector of boolean values, indicating for each element whether to store at memory or not.

free​

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

Please refer to UnsafePointer.free.

bitcast​

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

Please refer to UnsafePointer.bitcast.

Parameters:

Returns:

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

mut_cast​

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: A pointer with the same type, origin and address space as the original pointer, but with the newly specified mutability.

unsafe_mut_cast​

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: A pointer with the same type, origin and address space as the original pointer, but with the newly specified mutability.

unsafe_origin_cast​

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:

  • ​target_origin (Origin): Origin of the destination pointer.

Returns:

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

as_immutable​

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

Please refer to UnsafePointer.as_immutable.

Returns:

UnsafeNullablePointer: A pointer with the mutability set to immutable.

as_any_origin​

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

Please refer to UnsafePointer.as_any_origin.

Returns:

UnsafeNullablePointer: A pointer with the origin set to AnyOrigin.

address_space_cast​

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: A new UnsafeNullablePointer object with the same type and the same address, as the original UnsafeNullablePointer and the new address space.

destroy_pointee​

destroy_pointee[T: ImplicitlyDestructible, //](self: UnsafeNullablePointer[T, self.origin]) 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​

destroy_pointee_with(self: UnsafeNullablePointer[type, self.origin], 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​

take_pointee[T: Movable, //](self: UnsafeNullablePointer[T, self.origin]) -> 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​

init_pointee_move[T: Movable, //](self: UnsafeNullablePointer[T, self.origin], 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​

init_pointee_copy[T: Copyable, //](self: UnsafeNullablePointer[T, self.origin], 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​

init_pointee_move_from[T: Movable, //](self: UnsafeNullablePointer[T, self.origin], src: UnsafeNullablePointer[T, src.origin]) 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:

View source

View source

Was this page helpful?

Models

Cookbook

Puzzles

Blog

Community

Contact