extensions: Use Rust IO-safety types for fd/handle arguments/returns

Use Rust's IO-safety types like `OwnedFd`/`BorrowedFd` (and their
Windows `*Handle` equivalent) to communicate ownership transfer (or lack
thereof) to the user and provide automatic cleanup when an owned handle
is transferred to the caller.

For Windows however the returned handle is only owned when it is a
"handle type defined as NT handle" [1], being unclear what classifies as
an NT handle (anything built/used after 1993??).

We already contemplated this before, and the change puts `cfg(windows)`
and `cfg(unix)` guards in place for the corresponding OS-specific
extension wrappers, as these safety types are likewise only available on
the aforementioned platforms.

Unfortunately the import APIs pass file descriptors and handles via
structs which have non-trivial ownership transfer into Vulkan functions:
we could switch them to move semantics but there's no guarantee that
these structs are only used with these functions.  And it's even
more complicated for external memory import: there the handle / file
descriptor is passed in an `Info` struct chained in `pNext` for calls
to `vkAllocateMemory()`, making it even more complicated (if at all
possible) for us to intercept and "consume" the owned handle in a
wrapper layer to prevent Rust from closing it.

Furthermore note that all import APIs only transfer ownership _on Unix_;
on Windows the caller remains responsible for calling `CloseHandle()`
after (not sooner) the import is no longer used in Vulkan.

This bumps MSRV to 1.63, and we could switch from `std::os::unix::io` to
`std::os::fd` in MSRV 1.66.

[1]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetMemoryWin32HandleKHR.html#_description

Author: MarijnS95

.github/workflows/ci.yml

@@ -5,22 +5,31 @@ name: CI
 jobs:
   check:
     name: Check
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v1
       - run: cargo check --workspace --all-targets --all-features
 
   check_msrv:
-    name: Check ash MSRV (1.60.0)
-    runs-on: ubuntu-latest
+    name: Check ash MSRV (1.63.0)
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v1
-      - uses: dtolnay/rust-toolchain@1.60.0
+      - uses: dtolnay/rust-toolchain@1.63.0
       - run: cargo check -p ash -p ash-rewrite --all-features
 
   check_ash_window_msrv:
     name: Check ash-window MSRV (1.64.0)
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v1
       - uses: dtolnay/[email protected]

Changelog.md

@@ -42,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Define `Display` as `c_void` instead of `*mut c_void` to match Xlib (#751)
 - `VK_KHR_device_group_creation`: Take borrow of `Entry` in `fn new()` (#753)
 - `VK_KHR_device_group_creation`: Rename `vk::Instance`-returning function from `device()` to `instance()` (#759)
+- Use Rust IO-safety types (`OwnedFd`, `BorrowedFd`, `OwnedHandle`, `BorrowedHandle`) in functions to signify ownership transfer (#791)
 
 ### Removed
 

ash/Cargo.toml

@@ -13,7 +13,7 @@ readme = "../README.md"
 keywords = ["vulkan", "graphic"]
 documentation = "https://docs.rs/ash"
 edition = "2021"
-rust-version = "1.60.0"
+rust-version = "1.63.0"
 
 [dependencies]
 libloading = { version = "0.7", optional = true }

ash/src/extensions/ext/acquire_drm_display.rs

@@ -1,8 +1,11 @@
+#![cfg(unix)]
+
 use crate::prelude::*;
 use crate::vk;
 use crate::{Entry, Instance};
 use std::ffi::CStr;
 use std::mem;
+use std::os::unix::io::{AsRawFd, BorrowedFd};
 
 /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_acquire_drm_display.html>
 #[derive(Clone)]
@@ -24,23 +27,28 @@ impl AcquireDrmDisplay {
     pub unsafe fn acquire_drm_display(
         &self,
         physical_device: vk::PhysicalDevice,
-        drm_fd: i32,
+        drm_fd: BorrowedFd<'_>,
         display: vk::DisplayKHR,
     ) -> VkResult<()> {
-        (self.fp.acquire_drm_display_ext)(physical_device, drm_fd, display).result()
+        (self.fp.acquire_drm_display_ext)(physical_device, drm_fd.as_raw_fd(), display).result()
     }
 
     /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkGetDrmDisplayEXT.html>
     #[inline]
     pub unsafe fn get_drm_display(
         &self,
         physical_device: vk::PhysicalDevice,
-        drm_fd: i32,
+        drm_fd: BorrowedFd<'_>,
         connector_id: u32,
     ) -> VkResult<vk::DisplayKHR> {
         let mut display = mem::MaybeUninit::uninit();
-        (self.fp.get_drm_display_ext)(physical_device, drm_fd, connector_id, display.as_mut_ptr())
-            .assume_init_on_success(display)
+        (self.fp.get_drm_display_ext)(
+            physical_device,
+            drm_fd.as_raw_fd(),
+            connector_id,
+            display.as_mut_ptr(),
+        )
+        .assume_init_on_success(display)
     }
 
     pub const NAME: &'static CStr = vk::ExtAcquireDrmDisplayFn::NAME;

ash/src/extensions/ext/mod.rs

@@ -1,3 +1,4 @@
+#[cfg(unix)]
 pub use self::acquire_drm_display::AcquireDrmDisplay;
 pub use self::buffer_device_address::BufferDeviceAddress;
 pub use self::calibrated_timestamps::CalibratedTimestamps;

ash/src/extensions/khr/external_fence_fd.rs

@@ -1,8 +1,12 @@
+#![cfg(unix)]
+
 use crate::prelude::*;
 use crate::vk;
 use crate::{Device, Instance};
 use std::ffi::CStr;
 use std::mem;
+// use std::os::fd::OwnedFd;
+use std::os::unix::io::{FromRawFd, OwnedFd};
 
 #[derive(Clone)]
 pub struct ExternalFenceFd {
@@ -27,9 +31,10 @@ impl ExternalFenceFd {
 
     /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkGetFenceFdKHR.html>
     #[inline]
-    pub unsafe fn get_fence_fd(&self, get_info: &vk::FenceGetFdInfoKHR) -> VkResult<i32> {
+    pub unsafe fn get_fence_fd(&self, get_info: &vk::FenceGetFdInfoKHR) -> VkResult<OwnedFd> {
         let mut fd = -1;
-        (self.fp.get_fence_fd_khr)(self.handle, get_info, &mut fd).result_with_success(fd)
+        (self.fp.get_fence_fd_khr)(self.handle, get_info, &mut fd).result()?;
+        Ok(OwnedFd::from_raw_fd(fd))
     }
 
     pub const NAME: &'static CStr = vk::KhrExternalFenceFdFn::NAME;

ash/src/extensions/khr/external_fence_win32.rs

@@ -1,8 +1,11 @@
+#![cfg(windows)]
+
 use crate::prelude::*;
 use crate::vk;
 use crate::{Device, Instance};
 use std::ffi::CStr;
 use std::mem;
+use std::os::windows::io::{FromRawHandle, OwnedHandle};
 use std::ptr;
 
 /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_fence_win32.html>
@@ -35,10 +38,10 @@ impl ExternalFenceWin32 {
     pub unsafe fn get_fence_win32_handle(
         &self,
         get_info: &vk::FenceGetWin32HandleInfoKHR,
-    ) -> VkResult<vk::HANDLE> {
+    ) -> VkResult<OwnedHandle> {
         let mut handle = ptr::null_mut();
-        (self.fp.get_fence_win32_handle_khr)(self.handle, get_info, &mut handle)
-            .result_with_success(handle)
+        (self.fp.get_fence_win32_handle_khr)(self.handle, get_info, &mut handle).result()?;
+        Ok(OwnedHandle::from_raw_handle(handle))
     }
 
     pub const NAME: &'static CStr = vk::KhrExternalFenceWin32Fn::NAME;

ash/src/extensions/khr/external_memory_fd.rs

@@ -1,8 +1,11 @@
+#![cfg(unix)]
+
 use crate::prelude::*;
 use crate::vk;
 use crate::{Device, Instance};
 use std::ffi::CStr;
 use std::mem;
+use std::os::unix::io::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
 
 /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory_fd.html>
 #[derive(Clone)]
@@ -22,21 +25,27 @@ impl ExternalMemoryFd {
 
     /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkGetMemoryFdKHR.html>
     #[inline]
-    pub unsafe fn get_memory_fd(&self, get_fd_info: &vk::MemoryGetFdInfoKHR) -> VkResult<i32> {
+    pub unsafe fn get_memory_fd(&self, get_fd_info: &vk::MemoryGetFdInfoKHR) -> VkResult<OwnedFd> {
         let mut fd = -1;
-        (self.fp.get_memory_fd_khr)(self.handle, get_fd_info, &mut fd).result_with_success(fd)
+        (self.fp.get_memory_fd_khr)(self.handle, get_fd_info, &mut fd).result()?;
+        Ok(OwnedFd::from_raw_fd(fd))
     }
 
     /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkGetMemoryFdPropertiesKHR.html>
     #[inline]
     pub unsafe fn get_memory_fd_properties(
         &self,
         handle_type: vk::ExternalMemoryHandleTypeFlags,
-        fd: i32,
+        fd: BorrowedFd<'_>,
         memory_fd_properties: &mut vk::MemoryFdPropertiesKHR,
     ) -> VkResult<()> {
-        (self.fp.get_memory_fd_properties_khr)(self.handle, handle_type, fd, memory_fd_properties)
-            .result()
+        (self.fp.get_memory_fd_properties_khr)(
+            self.handle,
+            handle_type,
+            fd.as_raw_fd(),
+            memory_fd_properties,
+        )
+        .result()
     }
 
     pub const NAME: &'static CStr = vk::KhrExternalMemoryFdFn::NAME;

ash/src/extensions/khr/external_memory_win32.rs

@@ -1,8 +1,11 @@
+#![cfg(windows)]
+
 use crate::prelude::*;
 use crate::vk;
 use crate::{Device, Instance};
 use std::ffi::CStr;
 use std::mem;
+use std::os::windows::io::{AsRawHandle, BorrowedHandle, FromRawHandle, OwnedHandle};
 use std::ptr;
 
 /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory_win32.html>
@@ -26,24 +29,24 @@ impl ExternalMemoryWin32 {
     pub unsafe fn get_memory_win32_handle(
         &self,
         create_info: &vk::MemoryGetWin32HandleInfoKHR,
-    ) -> VkResult<vk::HANDLE> {
+    ) -> VkResult<OwnedHandle> {
         let mut handle = ptr::null_mut();
-        (self.fp.get_memory_win32_handle_khr)(self.handle, create_info, &mut handle)
-            .result_with_success(handle)
+        (self.fp.get_memory_win32_handle_khr)(self.handle, create_info, &mut handle).result()?;
+        Ok(OwnedHandle::from_raw_handle(handle))
     }
 
     /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkGetMemoryWin32HandlePropertiesKHR.html>
     #[inline]
     pub unsafe fn get_memory_win32_handle_properties(
         &self,
         handle_type: vk::ExternalMemoryHandleTypeFlags,
-        handle: vk::HANDLE,
+        handle: BorrowedHandle<'_>,
         memory_win32_handle_properties: &mut vk::MemoryWin32HandlePropertiesKHR,
     ) -> VkResult<()> {
         (self.fp.get_memory_win32_handle_properties_khr)(
             self.handle,
             handle_type,
-            handle,
+            handle.as_raw_handle(),
             memory_win32_handle_properties,
         )
         .result()

ash/src/extensions/khr/external_semaphore_fd.rs

@@ -1,8 +1,11 @@
+#![cfg(unix)]
+
 use crate::prelude::*;
 use crate::vk;
 use crate::{Device, Instance};
 use std::ffi::CStr;
 use std::mem;
+use std::os::unix::io::{FromRawFd, OwnedFd};
 
 #[derive(Clone)]
 pub struct ExternalSemaphoreFd {
@@ -30,9 +33,13 @@ impl ExternalSemaphoreFd {
 
     /// <https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkGetSemaphoreFdKHR.html>
     #[inline]
-    pub unsafe fn get_semaphore_fd(&self, get_info: &vk::SemaphoreGetFdInfoKHR) -> VkResult<i32> {
+    pub unsafe fn get_semaphore_fd(
+        &self,
+        get_info: &vk::SemaphoreGetFdInfoKHR,
+    ) -> VkResult<OwnedFd> {
         let mut fd = -1;
-        (self.fp.get_semaphore_fd_khr)(self.handle, get_info, &mut fd).result_with_success(fd)
+        (self.fp.get_semaphore_fd_khr)(self.handle, get_info, &mut fd).result()?;
+        Ok(OwnedFd::from_raw_fd(fd))
     }
 
     pub const NAME: &'static CStr = vk::KhrExternalSemaphoreFdFn::NAME;