feat(virtq): add producer side batch API

Signed-off-by: Tomasz Andrzejak <andreiltd@gmail.com>

Author: andreiltd

src/hyperlight_common/src/virtq/buffer.rs

@@ -117,15 +117,37 @@ impl<P: BufferProvider, M: MemOps> Drop for BufferOwner<P, M> {
     }
 }
 
+impl<P: BufferProvider, M: MemOps> BufferOwner<P, M> {
+    pub(crate) fn try_new(
+        pool: P,
+        mem: M,
+        alloc: Allocation,
+        written: usize,
+    ) -> Result<Self, M::Error> {
+        // Pre check direct access before handing the owner to Bytes::from_owner
+        let len = written.min(alloc.len);
+        let _ = unsafe { mem.as_slice(alloc.addr, len) }?;
+
+        Ok(Self {
+            pool,
+            mem,
+            alloc,
+            written,
+        })
+    }
+}
+
 impl<P: BufferProvider, M: MemOps> AsRef<[u8]> for BufferOwner<P, M> {
     fn as_ref(&self) -> &[u8] {
         let len = self.written.min(self.alloc.len);
-        // Safety: BufferOwner keeps both the pool allocation and the M
-        // alive, so the memory region is valid. Protocol-level descriptor
-        // ownership transfer guarantees no concurrent writes.
+        // Safety: BufferOwner keeps both the pool allocation and the M alive,
+        // so the memory region is valid.
         match unsafe { self.mem.as_slice(self.alloc.addr, len) } {
             Ok(slice) => slice,
-            Err(_) => &[],
+            Err(_) => {
+                debug_assert!(false, "BufferOwner direct slice failed");
+                &[]
+            }
         }
     }
 }

src/hyperlight_common/src/virtq/mod.rs

@@ -79,17 +79,21 @@ limitations under the License.
 //!
 //! ## Multiple Entries
 //!
-//! Each submit checks event suppression and notifies independently:
+//! Each submit checks event suppression and notifies independently. Use
+//! [`VirtqProducer::batch`] when a higher-level protocol wants to publish
+//! multiple entries and kick the queue once.
 //!
 //! ```ignore
+//! let mut batch = producer.batch();
 //! for data in entries {
-//!     let mut se = producer.chain()
+//!     let mut se = batch.chain()
 //!         .entry(data.len())
 //!         .completion(64)
 //!         .build()?;
 //!     se.write_all(data)?;
-//!     producer.submit(se)?;
+//!     batch.submit(se)?;
 //! }
+//! batch.finish()?;
 //! ```
 //!
 //! ## Completion Batching with Event Suppression