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; eitherInt
orUInt
.
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; eitherInt
orUInt
.
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; eitherInt
orUInt
.
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; eitherInt
orUInt
.
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; eitherInt
orUInt
.
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; eitherInt
orUInt
.
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, eitherInt
orUInt
. - β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, eitherInt
orUInt
. - β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 ofval
, 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 thedefault
SIMD vector. - βdefault (
SIMD[type, width]
): The SIMD vector providing default values to be taken where themask
SIMD vector isFalse
.
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 ofvalue
, 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 beMovable
.
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 beMovable
.
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 beCopyable
.
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 beExplicitlyCopyable
.
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 beMovable
.
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.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!
π What went wrong?