`unique_ptr` vs `shared_ptr` for resource objects (Textures, Buffers, etc)

[manon-traverse]

We need to reach a consensus on whether using shared_ptr is fine for ownership of resources like Buffers and Textures.
In order to have this discussion without it spreading over many PRs, we can centralize it here in an issue.

To kick off the conversation, here are my thoughts on the topic:

Why shared_ptr for resources in the first place?

Managing lifetimes of GPU resources requires more thought than resources because there is also the GPU timeline to take into account. If a Buffer is freed while it is still being used on the GPU, it will cause a DEVICE_LOST error. Since those errors are quite difficult to track down, usually some sort of 'keep-alive' system is used.

A code sketch demonstrating the issue:

auto Cmd = Queue.createCommandBuffer();

// Imagine this being somewhere 5 function calls deep.
{
   shared_ptr<Buffe> Buffer = Device.createBuffer(...);
   auto DescriptorSet = DescriptorSetBuilder().read(Buffer).Build(Device, Cmd, Pipeline);
   Cmd.dispatch(Pipeline, 1024, 1024, 1, DescriptorSet);
   // Buffer cleaned-up here
}

uint64_t SyncValue = Queue.submit(Cmd, Fence); // DEVICE_LOST
Fence.waitForCompletion(SyncValue);

Keep-Alive System
The simplest form of a keep-alive system is to give shared ownership of resources used on a command buffer to the command buffer. Once the command buffer has been submitted and we have synced with the GPU, we can go through the keep-alive list and release ownership. It is at that point that resources are cleaned up if there are no other owners.

A little sketch of what this would look like:

auto Cmd = Queue.createCommandBuffer(); // Frees any KeepAlive lists of synced command buffers

// Imagine this being somewhere 5 function calls deep.
{
   shared_ptr<Buffe> Buffer = Device.createBuffer(...);
   auto DescriptorSet = DescriptorSetBuilder().read(Buffer).Build(Device, Cmd, Pipeline);
   Cmd.dispatch(Pipeline, 1024, 1024, 1, DescriptorSet); // Add resources used in DescriptorSet to Cmd's KeepAlive list.
}

uint64_t SyncValue = Queue.submit(Cmd, Fence);
Fence.waitForCompletion(SyncValue);

// Next time the Queue creates a CommandBuffer or the Queue is cleaned up, the command buffer's KeepAlive list is cleared.

Keep-Alive systems can also be built using unique_ptr by introducing a retire_resource function on the command buffer. However, this means that resources need to be cleaned up manually. If the user forgets to release ownership of the resource using retireResource, there is a risk of freeing the resource too soon and triggering a DEVICE_LOST error. A way to deal with this problem is to log/assert when the user doesn't free the resources via the retireResource route, but it is not as robust as going the shared_ptr route.

A code sketch of what the unique_ptr variant would look like

auto Cmd = Queue.createCommandBuffer(); // Frees any KeepAlive lists of synced command buffers

// Imagine this being somewhere 5 function calls deep.
{
   unique_ptr<Buffe> Buffer = Device.createBuffer(...);
   auto DescriptorSet = DescriptorSetBuilder().read(Buffer.get()).Build(Device, Cmd, Pipeline);
   Cmd.dispatch(Pipeline, 1024, 1024, 1, DescriptorSet);
   Cmd.retireResource(std::move(Buffer)); // Must not forget to call this
}

uint64_t SyncValue = Queue.submit(Cmd, Fence);
Fence.waitForCompletion(SyncValue);

// Next time the Queue creates a CommandBuffer or the Queue is cleaned up, the command buffer's KeepAlive list is cleared.

My preference goes out to automatic resource tracking using shared_ptr, as there is one less step that needs to be remembered by the user.

shared_ptr Critique Points

The main critique of using shared_ptr comes down to two main issues:

1. Performance overhead: Copying a shared_ptr requires an atomic add operation, which can be expensive in cases where many of them are copied.
2. Unclear Management of Ownership: shared_ptr breaks the single-ownership idiom by having shared ownership. This makes it less clear what is supposed to own what, and when resources are being released.

Regarding Performance (Point 1): This type of performance overhead only becomes significant when there is a large number of them being copied. On the scale of running the testing framework, I am more concerned with initializing a device for each test than with using a couple of shared pointers, performance-wise.

Regarding Ownership( Point 2): Because managing the resource lifetimes of resources that are used on the CPU and GPU timeline is more complicated, ownership rules are always going to be a bit trickier. When the choice is between: 1. manually keep track of CPU and GPU timelines, 2. move ownership manually on the command buffer, or 3. tracking automatically, option 3 sounds like the option that is going to be the most robust.

Please let me know what your thoughts on this are. I am open to discussion.

[s-perron]

Thanks for opening the issue. It will be a good place to consolidate the discussion.

I find it hard to know exactly how to respond. I'll try to give a general concern.

1. Using std::shared_ptr does not mean you do not have to think about the lifetime of objects.

In Vulkan, the VkBuffer object is a handle to the buffer. Other things can happen that can invalidate that handle. For example, if the device is destroyed, the handle is not longer valid. Having an std::shared_ptr does not guarantee that the buffer is valid.

More that that consider VUID-vkDestroyDevice-device-05137. You have to make sure that all of the buffer are destroyed before deleting the device. To do that, you have to make sure that all instances of the shared pointer are destroyed before the device is destroyed.

A solution to this is to have every object have an std:shared_ptr pointing back to it parent object. For the Buffer, that is the device. However this is multiplying the number of shared pointers.

This all requires careful design. Even if you use shared pointer you still have to "manually keep track of CPU and GPU timelines" through some mechanism.

In general, I find the single owner model easier to reason about than the shared ownership model. For a single owner, all I have to think about it "Does the owner of this object outlive all of its uses?" For the shared ownership model, I need to ask "Does the union of the life times of the possible owner cover all of its uses?".

I think we should default to the single owner model because it is easier to reason about in a code review.

2. The example provided

The snippet seems over simplified, or there are other assumption that could be made more explicit.

The way the snippet is written it seems like a buffer will only be used with a single command buffer. If that is the case, then we could have the factory function be part of the command buffer instead of the device, and the command buffer could keep the ownership. This seems to be the way you are dealing with command buffers. The comment "// Frees any KeepAlive lists of synced command buffers", suggests that there can be only a single command buffer for that queue. When you create a new one, you can release the buffers associated with other command buffers.

Here is how the command buffer ownership would look:

auto Cmd = Queue.createCommandBuffer();

// Imagine this being somewhere 5 function calls deep.
{
    // Cmd will be responsible for deleting the buffer when it is done. 
    // We know that because it  returns a raw pointer.
   Buffer* Buf = Cmd.createBuffer(...); 

   // As is, it is unclear if DescriptorSet will be deleted at the end of the scope or not.
   // If `auto` is `DescritporSet`,  then the destructor will be called as the end of the scope.
   // Is is a shared_ptr, that is copied in the call to Dispatch?
   auto DescriptorSet = DescriptorSetBuilder().read(Buf).Build(Device, Cmd, Pipeline);
   Cmd.dispatch(Pipeline, 1024, 1024, 1, DescriptorSet);
}

uint64_t SyncValue = Queue.submit(Cmd, Fence);
Fence.waitForCompletion(SyncValue);

I'm not suggesting this is the best design. We need to consider the different uses of the Buffer/Texture. Then we can determine the best owner(s) for the buffer and texture. I just don't find that example compelling.

[devshgraphicsprogramming]

Shared pointers work just fine for us we did a whole Vulkanised 2026 talk about it. We std::move the shared pointers most of the time so we skip the atomic. Albeit you can 100% make a similar system work with other forms of garbage collection.

But if you're going to be using shared, then use shared_from_this because you're more likely to make things measurably slower by having a 16 byte handle instead of 8 byte than pounding the atomic.

p.s. when you get to TLAS tracking what BLAS are built into it or descriptor buffers being updated by the device timeline itself, no matter what you use, things will get a bit finnicky.

[manon-traverse]

Shared pointers work just fine for us we did a whole Vulkanised 2026 talk about it. We std::move the shared pointers most of the time so we skip the atomic. Albeit you can 100% make a similar system work with other forms of garbage collection.

But if you're going to be using shared, then use shared_from_this because you're more likely to make things measurably slower by having a 16 byte handle instead of 8 byte than pounding the atomic.

p.s. when you get to TLAS tracking what BLAS are built into it or descriptor buffers being updated by the device timeline itself, no matter what you use, things will get a bit finnicky.

I hadn't heard of shared_from_this before. I'll check it out and see if we can use it. 8-byte handles sound a lot nicer than 16-byte handles indeed!

As for the TLAS and BLAS tracking, yes, that will become complicated as the TLAS handle will also be holding references to the BLAS handle, and managing a keep-alive list for every instance becomes unrealistic.

What we did in Evolve is to have a World system manage the large number of assets in the scene in such a way that we keep things alive for a couple of extra frames due to bindless access and keep-alive tracking to become too large an overhead. These would be resources like buffers for models, textures, and acceleration structures. However, we would fully rely on a keep-alive system for all other resources (render targets, intermediate buffers, atomic counters, pipelines, etc) as we can track when they are used in a frame without it becoming unreasonable.

[manon-traverse]

Thanks for opening the issue. It will be a good place to consolidate the discussion.

I find it hard to know exactly how to respond. I'll try to give a general concern.

1. Using `std::shared_ptr` does not mean you do not have to think about the lifetime of objects.

In Vulkan, the VkBuffer object is a handle to the buffer. Other things can happen that can invalidate that handle. For example, if the device is destroyed, the handle is not longer valid. Having an std::shared_ptr does not guarantee that the buffer is valid.

More that that consider VUID-vkDestroyDevice-device-05137. You have to make sure that all of the buffer are destroyed before deleting the device. To do that, you have to make sure that all instances of the shared pointer are destroyed before the device is destroyed.

A solution to this is to have every object have an std:shared_ptr pointing back to it parent object. For the Buffer, that is the device. However this is multiplying the number of shared pointers.

This all requires careful design. Even if you use shared pointer you still have to "manually keep track of CPU and GPU timelines" through some mechanism.

In general, I find the single owner model easier to reason about than the shared ownership model. For a single owner, all I have to think about it "Does the owner of this object outlive all of its uses?" For the shared ownership model, I need to ask "Does the union of the life times of the possible owner cover all of its uses?".

I think we should default to the single owner model because it is easier to reason about in a code review.

Thank you for addressing this concern. This is not the type of bug we are aiming to solve with the shared_ptrs and keep_alive system. In fact, the issue you raise here is one you cannot solve with unique_ptr either, since they provide no guarantees over where the unique_ptrs get stored, and it ends up being up to the user of these handles to make sure objects are cleaned up in the right order. However, I don't see this as a large issue, mainly because you always initialize your devices once and always clean them up at the end. On top of that, as you point out, there is a validation layer error for this very case, which makes it a relatively simple issue to debug. I do agree that we should be careful with how we manage who owns which shared_ptr objects. As for triggering that specific issue I only really see that going wrong if someone were to store those in a global, which is a whole separate can of worms on its own.

The issue we aim to solve with shared_ptr is to solve an issue that is much more difficult to track down and solve, where the only debug information you get is 'the GPU crashed, good luck', aka DEVICE_LOST. This would be from textures or buffers being dropped and freed while they are still referenced/used on a command buffer that is going to be submitted or perhaps is already in flight. These issues are really difficult to track down, although some tooling exists these days to help here; it is far from reliable and not available on every vendor/platform.

My main issue with using unique_ptr is that the keep_alive system becomes something you need to remember to do, just like manual memory management, which in practice always ends up in programmers forgetting to call the thing (hence we use smart pointers where possible these days).

2. The example provided

The snippet seems over simplified, or there are other assumption that could be made more explicit.

The way the snippet is written it seems like a buffer will only be used with a single command buffer. If that is the case, then we could have the factory function be part of the command buffer instead of the device, and the command buffer could keep the ownership. This seems to be the way you are dealing with command buffers. The comment "// Frees any KeepAlive lists of synced command buffers", suggests that there can be only a single command buffer for that queue. When you create a new one, you can release the buffers associated with other command buffers.

Here is how the command buffer ownership would look:

auto Cmd = Queue.createCommandBuffer();

// Imagine this being somewhere 5 function calls deep.
{
    // Cmd will be responsible for deleting the buffer when it is done. 
    // We know that because it  returns a raw pointer.
   Buffer* Buf = Cmd.createBuffer(...); 

   // As is, it is unclear if DescriptorSet will be deleted at the end of the scope or not.
   // If `auto` is `DescritporSet`,  then the destructor will be called as the end of the scope.
   // Is is a shared_ptr, that is copied in the call to Dispatch?
   auto DescriptorSet = DescriptorSetBuilder().read(Buf).Build(Device, Cmd, Pipeline);
   Cmd.dispatch(Pipeline, 1024, 1024, 1, DescriptorSet);
}

uint64_t SyncValue = Queue.submit(Cmd, Fence);
Fence.waitForCompletion(SyncValue);

I'm not suggesting this is the best design. We need to consider the different uses of the Buffer/Texture. Then we can determine the best owner(s) for the buffer and texture. I just don't find that example compelling.

Adding createBuffer to the command buffer is not a good idea, mainly because creating a buffer has nothing to do with the command buffer. The command buffer only becomes relevant if data needs to be read/written to the buffer on the GPU timeline. I concede that my examples weren't that great, I mainly tried to sketch that 1. if we don't have any form of keep-alive system, we can easily run into hard-to-debug DEVICE_LOST issues, 2. if we use a unique_ptr approach the keep-alive system becomes a thing you need to remember to use, and 3. shared_ptr allows us to make this system fully automatic.

As for the command buffers, how I am roughly envisioning this is: {The queue keeps a pool of command buffers around. When the user wants to 'create' a command buffer, they get one from the pool that has finished syncing. If there is none, an actual new command buffer is created. At this point, since we need to check which command buffers in the pool have finished, we can first do a loop to release any keep-alive lists for command buffers that are now completed. This way, we don't limit how many command buffers we can have in flight and don't unnecessarily destroy and recreate command buffers.} This is also the strategy we used in the Evolve benchmark and has worked quite well for us before.

I'll see if I can write some better examples for you, and try to communicate why I think using the shared_ptr is the way to go once I am back in the office on Monday. Let me know if there are any other points you would like to see the examples address.