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

Mojo struct

DevicePointer

struct DevicePointer[mut: Bool, //, dtype: DType, origin: Origin[mut=mut]]

A host-side representation of a pointer to device memory that resides within a DeviceBuffer.

A DevicePointer is a non-owning borrow of a DeviceBuffer; it must not outlive the buffer it points into.

  • Supports pointer arithmetic which may result in a new DevicePointer instance referring to the same DeviceBuffer with a new offset.
  • Supports equality comparison and ordering of DevicePointers pointing into the same DeviceBuffer.
  • May support accessing device pointer address on supported hardware.
  • Does not support load/store operations.

At the device function execution boundary a DevicePointer is transformed into a Pointer on the device at the point of being handed over to the device driver.

Parameters​

  • ​mut (Bool): Whether the borrow of the underlying DeviceBuffer is mutable (inferred from origin).
  • ​dtype (DType): Data dtype to be stored in the pointer.
  • ​origin (Origin[mut=mut]): The origin of the borrowed DeviceBuffer.

Implemented traits​

AnyType, Copyable, Deinitable, DevicePassable, DevicePointerLike, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable, Writable

comptime members​

device_type​

comptime device_type = Pointer[Scalar[dtype], MutUnsafeAnyOrigin]

DevicePointer is remapped to a device Pointer when passed to accelerator devices.

PointeeType​

comptime PointeeType = Scalar[dtype]

DevicePointerLike encoded pointer pointee type.

Methods​

__init__​

def __init__(out self, ref[origin] buffer: DeviceBuffer[dtype])

Constructs a DevicePointer referencing the start of buffer.

Args:

  • ​buffer (DeviceBuffer[dtype]): The DeviceBuffer this pointer references. Must outlive the resulting DevicePointer.

Raises:

If buffer has size 0.

def __init__(out self, ref[origin] buffer: DeviceBuffer[dtype], offset: Int)

Constructs a DevicePointer into buffer at offset with size elements in range.

Args:

  • ​buffer (DeviceBuffer[dtype]): The DeviceBuffer this pointer references. Must outlive the resulting DevicePointer.
  • ​offset (Int): Element offset from the start of buffer.

Raises:

If buffer has size 0, or if offset is outside the half-open range [0, len(buffer)).

__lt__​

def __lt__(self, other: DevicePointer[dtype]) -> Bool

Returns True if self precedes other within the same buffer.

Args:

Returns:

Bool: True if self is ordered before other.

Raises:

If self and other reference different DeviceBuffers.

__le__​

def __le__(self, other: DevicePointer[dtype]) -> Bool

Returns True if self precedes or equals other within the same buffer.

Args:

Returns:

Bool: True if self is ordered before or equal to other.

Raises:

If self and other reference different DeviceBuffers.

__eq__​

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

Returns True if self and other reference the same buffer and offset.

Args:

  • ​other (Self): The other DevicePointer to compare.

Returns:

Bool: True if equal.

def __eq__(self, other: DevicePointer[dtype]) -> Bool

Returns True if self and other reference the same buffer and offset.

Args:

Returns:

Bool: True if equal.

__ne__​

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

Returns True if self and other differ in buffer or offset.

Args:

  • ​other (Self): The other DevicePointer to compare.

Returns:

Bool: True if not equal.

def __ne__(self, other: DevicePointer[dtype]) -> Bool

Returns True if self and other differ in buffer or offset.

Args:

Returns:

Bool: True if not equal.

__gt__​

def __gt__(self, other: DevicePointer[dtype]) -> Bool

Returns True if self follows other within the same buffer.

Args:

Returns:

Bool: True if self is ordered after other.

Raises:

If self and other reference different DeviceBuffers.

__ge__​

def __ge__(self, other: DevicePointer[dtype]) -> Bool

Returns True if self follows or equals other within the same buffer.

Args:

Returns:

Bool: True if self is ordered after or equal to other.

Raises:

If self and other reference different DeviceBuffers.

__add__​

def __add__(self, n: Int) -> Self

Returns a new DevicePointer offset forward by n elements.

Args:

  • ​n (Int): Number of elements to offset by.

Returns:

Self: A new DevicePointer referencing the same DeviceBuffer at the new offset.

Raises:

If the resulting offset is outside the bounds of the owning DeviceBuffer.

__sub__​

def __sub__(self, n: Int) -> Self

Returns a new DevicePointer offset backward by n elements.

Args:

  • ​n (Int): Number of elements to offset by.

Returns:

Self: A new DevicePointer referencing the same DeviceBuffer at the new offset.

Raises:

If the resulting offset is outside the bounds of the owning DeviceBuffer.

__iadd__​

def __iadd__(mut self, n: Int)

Offsets this DevicePointer forward by n elements in place.

Args:

  • ​n (Int): Number of elements to offset by.

Raises:

If the resulting offset is outside the bounds of the owning DeviceBuffer.

__isub__​

def __isub__(mut self, n: Int)

Offsets this DevicePointer backward by n elements in place.

Args:

  • ​n (Int): Number of elements to offset by.

Raises:

If the resulting offset is outside the bounds of the owning DeviceBuffer.

buffer​

def buffer(self) -> ref[origin] DeviceBuffer[dtype]

Returns a reference to the DeviceBuffer this pointer references.

The reference is non-owning; the underlying DeviceBuffer must outlive self.

Returns:

ref[origin] DeviceBuffer[dtype]: A reference to the referenced DeviceBuffer.

offset​

def offset(self) -> Int

Returns the element offset from the start of the owning buffer.

Returns:

Int: The element offset.

unsafe_mut_cast​

def unsafe_mut_cast[target_mut: Bool](self) -> DevicePointer[dtype, origin_of(origin)]

Changes the mutability of the borrow of the DeviceBuffer.

To unconditionally drop mutability use as_imm.

Safety: Casting an immutable borrow to mutable claims mutation rights the caller does not hold, which defeats exclusivity checking: mutating the DeviceBuffer through the result while another borrow of it is live is undefined behavior. Prefer binding the mutability at the function signature level, for example taking a DevicePointer[mut=True, dtype, _] argument over an unbound DevicePointer[dtype, _].

Parameters:

  • ​target_mut (Bool): Mutability of the resulting DevicePointer.

Returns:

DevicePointer[dtype, origin_of(origin)]: A DevicePointer referencing the same DeviceBuffer at the same offset, but with the newly specified mutability.

unsafe_origin_cast​

def unsafe_origin_cast[target_origin: Origin[mut=mut]](self) -> DevicePointer[dtype, target_origin]

Changes the origin of the borrow of the DeviceBuffer.

To unconditionally discard the origin use as_unsafe_any_origin.

Safety: The result names target_origin rather than the DeviceBuffer it refers into, so the lifetime checker no longer keeps that buffer alive; using the result once the buffer is destroyed is undefined behavior. Prefer parameterizing the origin at the function level over casting it.

Parameters:

  • ​target_origin (Origin[mut=mut]): Origin of the resulting DevicePointer.

Returns:

DevicePointer[dtype, target_origin]: A DevicePointer referencing the same DeviceBuffer at the same offset, but with the newly specified origin.

as_imm​

def as_imm(self) -> DevicePointer[dtype, origin_of(origin)]

Changes the borrow of the DeviceBuffer to immutable.

Unlike unsafe_mut_cast this is always safe: dropping mutability cannot introduce aliasing.

Returns:

DevicePointer[dtype, origin_of(origin)]: A DevicePointer referencing the same DeviceBuffer at the same offset, but with an immutable borrow.

as_unsafe_any_origin​

def as_unsafe_any_origin(self) -> DevicePointer[dtype, SomeUnsafeAnyOrigin]

Discards the origin of the borrow of the DeviceBuffer.

Safety: UnsafeAnyOrigin might alias any live value, which forces the lifetime checker into its most conservative behavior: it extends unrelated lifetimes and turns off exclusivity checking. The caller takes over keeping the DeviceBuffer alive. A concrete origin is always preferable.

Returns:

DevicePointer[dtype, SomeUnsafeAnyOrigin]: A DevicePointer with the origin set to UnsafeAnyOrigin.

write_to​

def write_to(self, mut writer: T)

Writes a string representation of this DevicePointer to writer.

Args:

  • ​writer (T): The writer to output the formatted string to.

get_type_name​

static def get_type_name() -> String

Gets this type's name, for use in error messages when handing arguments to kernels.

Returns:

String: This type's name.

Models

Cookbook

Puzzles

Blog

Community

Contact