ScopedWaiter

Author: karnkaul

guide/src/SUMMARY.md

@@ -14,3 +14,4 @@
   - [Vulkan Surface](initialization/surface.md)
   - [Vulkan Physical Device](initialization/gpu.md)
   - [Vulkan Device](initialization/device.md)
+  - [Scoped Waiter](initialization/scoped_waiter.md)

guide/src/initialization/device.md

@@ -57,3 +57,38 @@ Declare a `vk::Queue` member (order doesn't matter since it's just a handle, the
 	static constexpr std::uint32_t queue_index_v{0};
 	m_queue = m_device->getQueue(m_gpu.queue_family, queue_index_v);
 ```
+
+## ScopedWaiter
+
+A useful abstraction to have is an object that in its destructor waits/blocks until the Device is idle. Being able to do arbitary things on scope exit is useful in general too, but it requires some custom class template like `UniqueResource<Type, Deleter>`. We shall "abuse" `std::unique_ptr<Type, Deleter>` instead: it will not manage the pointer (`Type*`) at all, but instead `Deleter` will call a member function on it (if it isn't null).
+
+Adding this to a new header `scoped_waiter.hpp`:
+
+```cpp
+class ScopedWaiter {
+  public:
+	ScopedWaiter() = default;
+
+	explicit ScopedWaiter(vk::Device const* device) : m_device(device) {}
+
+  private:
+	struct Deleter {
+		void operator()(vk::Device const* device) const noexcept {
+			if (device == nullptr) { return; }
+			device->waitIdle();
+		}
+	};
+	std::unique_ptr<vk::Device const, Deleter> m_device{};
+};
+```
+
+This requires the passed `vk::Device*` to outlive itself, so to be defensive we make `App` be non-moveable and non-copiable, and create a member factory function for waiters:
+
+```cpp
+	auto operator=(App&&) = delete;
+// ...
+
+	[[nodiscard]] auto create_waiter() const -> ScopedWaiter {
+		return ScopedWaiter{&*m_device};
+	}
+```

guide/src/initialization/scoped_waiter.md

@@ -0,0 +1,64 @@
+# Scoped Waiter
+
+A useful abstraction to have is an object that in its destructor waits/blocks until the Device is idle. It is incorrect usage to destroy Vulkan objects while they are in use by the GPU, such an object helps with making sure the device is idle before some dependent resource gets destroyed.
+
+Being able to do arbitary things on scope exit will be useful in other spots too, so we encapsulate that in a basic class template `Scoped`. It's somewhat like a `unique_ptr<Type, Deleter>` that stores the value (`Type`) instead of a pointer (`Type*`), with some constraints:
+
+1. `Type` must be default constructible
+1. Assumes a default constructed `Type` is equivalent to null (does not call `Deleter`)
+
+```cpp
+template <typename Type>
+concept Scopeable =
+	std::equality_comparable<Type> && std::is_default_constructible_v<Type>;
+
+template <Scopeable Type, typename Deleter>
+class Scoped {
+  public:
+	Scoped(Scoped const&) = delete;
+	auto operator=(Scoped const&) = delete;
+
+	Scoped() = default;
+
+	constexpr Scoped(Scoped&& rhs) noexcept
+		: m_t(std::exchange(rhs.m_t, Type{})) {}
+
+	constexpr auto operator=(Scoped&& rhs) noexcept -> Scoped& {
+		if (&rhs != this) { std::swap(m_t, rhs.m_t); }
+		return *this;
+	}
+
+	explicit constexpr Scoped(Type t) : m_t(std::move(t)) {}
+
+	constexpr ~Scoped() {
+		if (m_t == Type{}) { return; }
+		Deleter{}(m_t);
+	}
+
+	[[nodiscard]] auto get() const -> Type const& { return m_t; }
+	[[nodiscard]] auto get() -> Type& { return m_t; }
+
+  private:
+	Type m_t{};
+};
+```
+
+Don't worry if this doesn't make a lot of sense: the implementation isn't important, what it does and how to use it is what matters.
+
+A `ScopedWaiter` can now be implemented quite easily:
+
+```cpp
+struct ScopedWaiterDeleter {
+	void operator()(vk::Device const device) const noexcept {
+		device.waitIdle();
+	}
+};
+
+using ScopedWaiter = Scoped<vk::Device, ScopedWaiterDeleter>;
+```
+
+Add a `ScopedWaiter` member to `App` _at the end_ of its member list: this must remain at the end to be the first member that gets destroyed, thus guaranteeing the device will be idle before the destruction of any other members begins. Initialize it after creating the Device:
+
+```cpp
+	m_waiter = ScopedWaiter{*m_device};
+```

src/app.cpp

@@ -1,6 +1,8 @@
 #include <app.hpp>
 #include <print>
 
+#include <thread>
+
 VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE
 
 namespace lvk {
@@ -79,12 +81,15 @@ void App::create_device() {
 	static constexpr std::uint32_t queue_index_v{0};
 	m_queue = m_device->getQueue(m_gpu.queue_family, queue_index_v);
 
-	// m_device_block.get() = *m_device;
+	m_waiter = ScopedWaiter{*m_device};
 }
 
 void App::main_loop() {
+	auto count = 0;
 	while (glfwWindowShouldClose(m_window.get()) == GLFW_FALSE) {
 		glfwPollEvents();
+		if (++count > 500) { break; }
+		std::this_thread::sleep_for(std::chrono::milliseconds{10});
 	}
 }
 } // namespace lvk

src/app.hpp

@@ -1,5 +1,6 @@
 #pragma once
 #include <gpu.hpp>
+#include <scoped_waiter.hpp>
 #include <vulkan/vulkan.hpp>
 #include <window.hpp>
 
@@ -23,5 +24,7 @@ class App {
 	Gpu m_gpu{};
 	vk::UniqueDevice m_device{};
 	vk::Queue m_queue{};
+
+	ScopedWaiter m_waiter{};
 };
 } // namespace lvk

src/scoped.hpp

@@ -0,0 +1,39 @@
+#pragma once
+#include <concepts>
+#include <utility>
+
+namespace lvk {
+template <typename Type>
+concept Scopeable =
+	std::equality_comparable<Type> && std::is_default_constructible_v<Type>;
+
+template <Scopeable Type, typename Deleter>
+class Scoped {
+  public:
+	Scoped(Scoped const&) = delete;
+	auto operator=(Scoped const&) = delete;
+
+	Scoped() = default;
+
+	constexpr Scoped(Scoped&& rhs) noexcept
+		: m_t(std::exchange(rhs.m_t, Type{})) {}
+
+	constexpr auto operator=(Scoped&& rhs) noexcept -> Scoped& {
+		if (&rhs != this) { std::swap(m_t, rhs.m_t); }
+		return *this;
+	}
+
+	explicit constexpr Scoped(Type t) : m_t(std::move(t)) {}
+
+	constexpr ~Scoped() {
+		if (m_t == Type{}) { return; }
+		Deleter{}(m_t);
+	}
+
+	[[nodiscard]] auto get() const -> Type const& { return m_t; }
+	[[nodiscard]] auto get() -> Type& { return m_t; }
+
+  private:
+	Type m_t{};
+};
+} // namespace lvk

src/scoped_waiter.hpp

@@ -0,0 +1,13 @@
+#pragma once
+#include <scoped.hpp>
+#include <vulkan/vulkan.hpp>
+
+namespace lvk {
+struct ScopedWaiterDeleter {
+	void operator()(vk::Device const device) const noexcept {
+		device.waitIdle();
+	}
+};
+
+using ScopedWaiter = Scoped<vk::Device, ScopedWaiterDeleter>;
+} // namespace lvk