# VZVirtioQueueElement A unit of work on a Virtio queue, also known as a descriptor chain. ``` class VZVirtioQueueElement ``` ## Overview A `VZVirtioQueueElement` represents a unit of work from a [`VZVirtioQueue`](/documentation/Virtualization/VZVirtioQueue) with which it’s associated, facilitating device operations specified by the [`VZCustomVirtioDevice`](/documentation/Virtualization/VZCustomVirtioDevice) that the `VZVirtioQueue` belongs to. It exposes the scatter-gather memory to the guest’s dynamic random access memory (DRAM) that the Virtio queue references as read buffers and write buffers; this allows for read-only and write-only access, respectively, to this memory on the host. It’s strongly recommended to access the read buffers and write buffers only *once* using the [`readBytes(withExactLength:)`](/documentation/Virtualization/VZVirtioQueueElement/readBytes(withExactLength:)), [`readBytes(intoBuffer:exactLength:)`](/documentation/Virtualization/VZVirtioQueueElement/readBytes(intoBuffer:exactLength:)), [`write(_:)`](/documentation/Virtualization/VZVirtioQueueElement/write(_:)), and [`writeBuffer(_:exactLength:)`](/documentation/Virtualization/VZVirtioQueueElement/writeBuffer(_:exactLength:)) methods. Those methods enforce that you only access the memory once and changes the value of [`readBuffersAvailableByteCount`](/documentation/Virtualization/VZVirtioQueueElement/readBuffersAvailableByteCount) and [`writeBuffersAvailableByteCount`](/documentation/Virtualization/VZVirtioQueueElement/writeBuffersAvailableByteCount) accordingly. The [`peekIntoReadBuffers(withExactLength:)`](/documentation/Virtualization/VZVirtioQueueElement/peekIntoReadBuffers(withExactLength:)) method allows for multiple read accesses if absolutely necessary and doesn’t change the value of [`readBuffersAvailableByteCount`](/documentation/Virtualization/VZVirtioQueueElement/readBuffersAvailableByteCount). > Important: Accessing this memory multiple times can introduce time-of-check time-of-use (TOCTOU) bugs which are prone to security attacks. Since the > guest is free to modify its memory at any time, two consecutive reads may return different results, and malicious guests can take advantage of > this to perform various attacks. Don’t instantiate `VZVirtioQueueElement` objects directly, the framework provides them through the [`nextElement()`](/documentation/Virtualization/VZVirtioQueue/nextElement()) method when you handle any elements in the Virtio queue. When you are done with processing the element, you need to call [`returnToQueue()`](/documentation/Virtualization/VZVirtioQueueElement/returnToQueue()) to return the element back to the guest. ## Topics ### Instance Properties [`var readBuffersAvailableByteCount: Int`](/documentation/Virtualization/VZVirtioQueueElement/readBuffersAvailableByteCount) The size of the read buffers memory (in bytes) exposed by the Virtio queue element that’s currently available for reading. [`var readBuffersByteCount: Int`](/documentation/Virtualization/VZVirtioQueueElement/readBuffersByteCount) The total size of the read buffers memory (in bytes) exposed by the Virtio queue element. [`var writeBuffersAvailableByteCount: Int`](/documentation/Virtualization/VZVirtioQueueElement/writeBuffersAvailableByteCount) The size of the write buffers memory (in bytes) exposed by the Virtio queue element that’s currently available for writing. [`var writeBuffersByteCount: Int`](/documentation/Virtualization/VZVirtioQueueElement/writeBuffersByteCount) The total size of the write buffers memory (in bytes) exposed by the Virtio queue element. [`var writtenByteCount: Int`](/documentation/Virtualization/VZVirtioQueueElement/writtenByteCount) The size of the write buffers memory exposed (in bytes) by the Virtio queue element that has already been written to. ### Instance Methods [`func peekIntoReadBuffers(withExactLength: Int) throws -> Data`](/documentation/Virtualization/VZVirtioQueueElement/peekIntoReadBuffers(withExactLength:)) Peeks into the read buffers and copy exactLength bytes from the read buffer into the data object it returns. [`func readBuffers() -> [Data]`](/documentation/Virtualization/VZVirtioQueueElement/readBuffers()) Gets the remaining read buffers memory represented as an array of data. [`func readBytes(intoBuffer: UnsafeMutableRawPointer, exactLength: Int) throws`](/documentation/Virtualization/VZVirtioQueueElement/readBytes(intoBuffer:exactLength:)) Reads the number of bytes you specify from the read buffers into the memory pointed to by the pointer to the buffer you provide. [`func readBytes(withExactLength: Int) throws -> Data`](/documentation/Virtualization/VZVirtioQueueElement/readBytes(withExactLength:)) Reads the number of bytes you specify from the read buffers and return result as a data object. [`func returnToQueue()`](/documentation/Virtualization/VZVirtioQueueElement/returnToQueue()) Returns this element back to the guest. [`func write(Data) throws`](/documentation/Virtualization/VZVirtioQueueElement/write(_:)) Writes the memory represented by the data object you provide into the write buffers. [`func writeBuffer(UnsafeMutableRawPointer, exactLength: Int) throws`](/documentation/Virtualization/VZVirtioQueueElement/writeBuffer(_:exactLength:)) Writes to the memory represented by the pointer to the buffer you provide to the write buffers. ## See Also [`class VZCustomVirtioDevice`](/documentation/Virtualization/VZCustomVirtioDevice) An interface that represents a custom Virtio device that you provide the implementation for. [`class VZVirtioQueue`](/documentation/Virtualization/VZVirtioQueue) A Virtio queue. ## Relationships ### Conforms To [`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible) [`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible) [`Equatable`](/documentation/Swift/Equatable) [`Hashable`](/documentation/Swift/Hashable) [`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol) [`CVarArg`](/documentation/Swift/CVarArg) ### Inherits From [`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)