MTLResidencySet
A collection of resource allocations that can move in and out of resident memory.
Declaration
protocol MTLResidencySet : NSObjectProtocolMentioned in
Overview
Residency sets are a way you can tell Metal which resource allocations, such as buffers, textures, and heaps, to make resident, or GPU-accessible. Adding allocations to a residency set requires less overhead than the equivalent methods of a command encoder. Residency sets also give you more control when Metal makes their allocations resident, and for how long they remain resident. However, residency sets don’t track hazards, so you need to account for hazards with fences and events.
You can change which MTLAllocation instances are in a residency set at any time by:
Staging additions and removals with the addAllocation(_:) and removeAllocation(_:) methods, respectively, or with their sibling methods
Applying staged changes by calling the residency set’s commit() method
Metal doesn’t synchronize the state of the residency set between the CPU and the GPU. This means you can add resource allocations to the set while the GPU is actively running a command buffer that’s accessing them.
Metal makes the union of all residency sets’ allocations resident. This means each resource allocation, such as a buffer, can have an entry in multiple residency sets at the same time. Removing an allocation from one residency set doesn’t affect its residency if it also has an entry in another residency set. So you can remove an entire residency set from a command queue and only remove the allocations from residency that are unique to that set. All other resource allocations remain in residency because at least one other residency set has an entry for each.
Alternatively, render and compute command encoders have the following methods that make resource allocations resident:
These command encoder methods:
Support hazard tracking to applicable resources (see Resource fundamentals)
Require CPU overhead for each resource or heap, which scale up with each one you add
Apply to a single command encoder, which means you need to call the methods again for the same resources for each command encoder
Residency sets, by contrast:
Don’t support hazard tracking, which means you need to account for hazards with MTLFence and MTLEvent instances
Require minimal CPU overhead by aggregating allocations at little to no cost for each resource or heap
Can attach to a command buffer with a single call, which makes residency set’s allocations available to all of that command buffer’s encoders
Can attach to a command queue with a single call
Metal attaches all of a command queue’s residency sets to a command buffer from that queue when you call the command buffer’s commit() method.
See Simplifying GPU resource management with residency sets for information about associating a residency set to command buffers and command queues.
Create a residency set
Make a residency set by configuring an MTLResidencySetDescriptor instance and passing it to the makeResidencySet(descriptor:) method of an MTLDevice.
Add allocations to a residency set
Add individual resource allocations to a residency set by calling addAllocation(_:), or add multiple allocations with addAllocations(_:).
The residency set can handle redundant entries for the same allocation because it ignores duplicates that already have an entry in the set.
Remove allocations from a residency set
Remove individual resource allocations from a residency set by calling removeAllocation(_:), or remove multiple allocations with removeAllocations(_:).
Like the methods that add resource allocations to the set, these methods aggregate removals with little CPU overhead. So you can call the methods multiple times without adversely affecting runtime performance.
Commit the changes to a residency set
Apply the updates to a residency set by calling its commit() method.
A residency set’s addition and removal methods don’t take effect until you call this method.