Skip to main content

/

Docs

Nightly

v25.1

Log in

Mojo struct

DeviceBuffer

struct DeviceBuffer[type: DType, address_space: AddressSpace = AddressSpace(0), mut: Bool = True, origin: Origin[mut] = SomeAnyOrigin]

Represents a block of device-resident storage. For GPU devices, a device buffer is allocated in the device's global memory.

To allocate a DeviceBuffer, use one of the methods provided by DeviceContext, such as enqueue_create_buffer().

Parameters​

  • ​type (DType): Data type to be stored in the buffer.
  • ​address_space (AddressSpace): The address space of the underlying pointer.
  • ​mut (Bool): The mutability of the underlying pointer.
  • ​origin (Origin[mut]): The origin of the underlying pointer.

Implemented traits​

AnyType, CollectionElement, Copyable, Movable, Sized, Stringable, UnknownDestructibility, Writable

Methods​

__copyinit__​

__copyinit__(out self, existing: Self)

Creates a copy of an existing device buffer by incrementing its reference count.

This copy constructor creates a new reference to the same underlying device buffer by incrementing the reference count of the native buffer object. Both the original and the copy will refer to the same memory on the device.

Args:

  • ​existing (Self): The device buffer to copy.

__moveinit__​

__moveinit__(out self, owned existing: Self)

Initializes this buffer by taking ownership of an existing buffer.

This move constructor transfers ownership of the device buffer from the existing instance to the new instance without incrementing the reference count.

Args:

  • ​existing (Self): The buffer to move from, which will no longer be valid after this call.

__del__​

__del__(owned self)

Releases resources associated with this device buffer.

This function schedules an owned buffer free using the stream in the device context. The actual deallocation may occur asynchronously after all operations using this buffer have completed.

__getitem__​

__getitem__(self, idx: Int) -> SIMD[type, 1]

Retrieves the element at the specified index from the device buffer.

This operator allows direct access to individual elements in the device buffer using array indexing syntax. The access is performed directly on device memory.

Args:

  • ​idx (Int): The index of the element to retrieve.

Returns:

The scalar value at the specified index.

__setitem__​

__setitem__(self: DeviceBuffer[type], idx: Int, val: SIMD[type, 1])

Sets the element at the specified index in the device buffer.

This operator allows direct modification of individual elements in the device buffer using array indexing syntax. The modification is performed directly on device memory.

Args:

  • ​idx (Int): The index of the element to modify.
  • ​val (SIMD[type, 1]): The new value to store at the specified index.

copy​

copy(self) -> Self

Explicitly construct a copy of self.

Returns:

A copy of this value.

__len__​

__len__(self) -> Int

Returns the number of elements in this buffer.

This method calculates the number of elements by dividing the total byte size of the buffer by the size of each element.

Returns:

The number of elements in the buffer.

create_sub_buffer​

create_sub_buffer[view_type: DType](self, offset: Int, size: Int) -> DeviceBuffer[view_type]

Creates a sub-buffer view of this buffer with a different element type.

This method creates a new buffer that references a subset of the memory in this buffer, potentially with a different element type. The sub-buffer shares the underlying memory with the original buffer.

Parameters:

  • ​view_type (DType): The data type for elements in the new sub-buffer.

Args:

  • ​offset (Int): The starting offset in elements from the beginning of this buffer.
  • ​size (Int): The number of elements in the new sub-buffer.

Returns:

A new DeviceBuffer referencing the specified region with the specified element type.

enqueue_copy_to​

enqueue_copy_to(self, dst: DeviceBuffer[type, address_space, mut, origin])

Enqueues an asynchronous copy from this buffer to another device buffer.

This method schedules a memory copy operation from this buffer to the destination buffer. The operation is asynchronous and will be executed in the stream associated with this buffer's context.

Args:

  • ​dst (DeviceBuffer[type, address_space, mut, origin]): The destination device buffer to copy data to.

enqueue_copy_to(self, dst_ptr: UnsafePointer[SIMD[type, 1]])

Enqueues an asynchronous copy from this buffer to host memory.

This method schedules a memory copy operation from this device buffer to the specified host memory location. The operation is asynchronous and will be executed in the stream associated with this buffer's context.

Args:

  • ​dst_ptr (UnsafePointer[SIMD[type, 1]]): Pointer to the destination host memory location.

enqueue_copy_from​

enqueue_copy_from(self, src: DeviceBuffer[type, address_space, mut, origin])

Enqueues an asynchronous copy to this buffer from another device buffer.

This method schedules a memory copy operation to this buffer from the source buffer. The operation is asynchronous and will be executed in the stream associated with this buffer's context.

Args:

  • ​src (DeviceBuffer[type, address_space, mut, origin]): The source device buffer to copy data from.

enqueue_copy_from(self, src_ptr: UnsafePointer[SIMD[type, 1]])

Enqueues an asynchronous copy to this buffer from host memory.

This method schedules a memory copy operation to this device buffer from the specified host memory location. The operation is asynchronous and will be executed in the stream associated with this buffer's context.

Args:

  • ​src_ptr (UnsafePointer[SIMD[type, 1]]): Pointer to the source host memory location.

enqueue_fill​

enqueue_fill(self, val: SIMD[type, 1]) -> Self

Enqueues an operation to fill this buffer with a specified value.

This method schedules a memory set operation that fills the entire buffer with the specified value. The operation is asynchronous and will be executed in the stream associated with this buffer's context.

Args:

  • ​val (SIMD[type, 1]): The value to fill the buffer with.

Returns:

Self reference for method chaining.

reassign_ownership_to​

reassign_ownership_to(self, ctx: DeviceContext)

Transfers ownership of this buffer to another device context.

This method changes the device context that owns this buffer. This can be useful when sharing buffers between different contexts or when migrating workloads between devices.

Args:

  • ​ctx (DeviceContext): The new device context to take ownership of this buffer.

take_ptr​

take_ptr(owned self) -> UnsafePointer[SIMD[type, 1], address_space=address_space, mut=mut, origin=origin]

Takes ownership of the device pointer from this buffer.

This method releases the device pointer from the buffer's control and returns it to the caller. After this call, the buffer no longer owns the pointer, and the caller is responsible for managing its lifecycle.

Returns:

The raw device pointer that was owned by this buffer.

unsafe_ptr​

unsafe_ptr(self) -> UnsafePointer[SIMD[type, 1], address_space=address_space, mut=mut, origin=origin]

Returns the raw device pointer without transferring ownership.

This method provides direct access to the underlying device pointer for advanced use cases. The buffer retains ownership of the pointer.

Returns:

The raw device pointer owned by this buffer.

context​

context(self) -> DeviceContext

Returns the device context associated with this buffer.

This method retrieves the device context that owns this buffer and is responsible for managing its lifecycle and operations.

Returns:

The device context associated with this buffer.

map_to_host​

map_to_host(self) -> _HostMappedBuffer[type, address_space, mut, origin]

Maps this device buffer to host memory for CPU access.

This method creates a host-accessible view of the device buffer's contents. The mapping operation may involve copying data from device to host memory.

Returns:

A host-mapped buffer that provides CPU access to the device buffer's contents.

write_to​

write_to[W: Writer](self, mut writer: W)

Writes a string representation of this buffer to the provided writer.

This method formats the buffer's contents as a string and writes it to the specified writer. For large buffers, a compact representation is used.

Parameters:

  • ​W (Writer): The writer type.

Args:

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

__str__​

__str__(self) -> String

Returns a string representation of the DeviceBuffer.

This method creates a human-readable string representation of the buffer's contents by mapping the device memory to host memory and formatting the elements.

Returns:

A string containing the formatted buffer contents.