Mojo struct
HostBuffer
struct HostBuffer[type: DType, address_space: AddressSpace = AddressSpace(0), mut: Bool = True, origin: Origin[mut] = SomeAnyOrigin]
Represents a block of host-resident storage. For GPU devices, a host buffer is allocated in the host's global memory.
To allocate a HostBuffer, use one of the methods provided by
DeviceContext, such as
enqueue_create_host_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,
Sized,
Stringable,
UnknownDestructibility,
Writable
Methods
__copyinit__
__copyinit__(out self, existing: Self)
Creates a copy of an existing host buffer by incrementing its reference count.
This copy constructor creates a new reference to the same underlying host 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 host 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 host 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 host buffer.
This operator allows direct access to individual elements in the host buffer using array indexing syntax.
Args:
- idx (
Int): The index of the element to retrieve.
Returns:
The scalar value at the specified index.
__setitem__
__setitem__(self: HostBuffer[type], idx: Int, val: SIMD[type, 1])
Sets the element at the specified index in the host buffer.
This operator allows direct modification of individual elements in the host buffer using array indexing syntax.
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) -> HostBuffer[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 HostBuffer referencing the specified region with the specified element type.
enqueue_copy_to
enqueue_copy_to(self, dst: HostBuffer[type, address_space, mut, origin])
Enqueues an asynchronous copy from this buffer to another host 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 (
HostBuffer[type, address_space, mut, origin]): The destination host buffer to copy data to.
enqueue_copy_to(self, dst: DeviceBuffer[type, address_space, mut, origin])
Enqueues an asynchronous copy from this buffer to a 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: HostBuffer[type, address_space, mut, origin])
Enqueues an asynchronous copy to this buffer from another host 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 (
HostBuffer[type, address_space, mut, origin]): The source host buffer to copy data from.
enqueue_copy_from(self, src: DeviceBuffer[type, address_space, mut, origin])
Enqueues an asynchronous copy to this buffer from a 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.
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 HostBuffer.
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.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!