--- title: MTLResidencySet framework: metal role: symbol role_heading: Protocol path: metal/mtlresidencyset --- # MTLResidencySet A collection of resource allocations that can move in and out of resident memory. ## Declaration ```swift protocol MTLResidencySet : NSObjectProtocol ``` ## Mentioned in Simplifying GPU resource management with residency sets ## Overview 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. important: If there’s a resource in a residency set that the GPU no longer needs access to, you can remove that resource from the residency set, even while the GPU is actively accessing other resources from the same residency set. 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. important: Residency sets don’t support sparse heaps or sparse textures, and their methods aren’t thread-safe. 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. important: Adding a resource, such as a buffer or texture, that originates from a heap to a residency set makes its entire heap resident. 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. ## Topics ### Adding allocations - [addAllocation(_:)](metal/mtlresidencyset/addallocation(_:).md) - [addAllocations(_:)](metal/mtlresidencyset/addallocations(_:).md) ### Removing allocations - [removeAllAllocations()](metal/mtlresidencyset/removeallallocations().md) - [removeAllocation(_:)](metal/mtlresidencyset/removeallocation(_:).md) - [removeAllocations(_:)](metal/mtlresidencyset/removeallocations(_:).md) ### Finalizing pending allocation changes - [commit()](metal/mtlresidencyset/commit().md) ### Requesting residency for the allocations - [requestResidency()](metal/mtlresidencyset/requestresidency().md) ### Releasing the allocations from residency - [endResidency()](metal/mtlresidencyset/endresidency().md) ### Inspecting a residency set - [label](metal/mtlresidencyset/label.md) - [device](metal/mtlresidencyset/device.md) - [containsAllocation(_:)](metal/mtlresidencyset/containsallocation(_:).md) - [allAllocations](metal/mtlresidencyset/allallocations.md) - [allocationCount](metal/mtlresidencyset/allocationcount.md) - [allocatedSize](metal/mtlresidencyset/allocatedsize.md) ## Relationships ### Inherits From - [NSObjectProtocol](objectivec/nsobjectprotocol.md) ## See Also ### Residency sets - [Simplifying GPU resource management with residency sets](metal/simplifying-gpu-resource-management-with-residency-sets.md) - [MTLResidencySetDescriptor](metal/mtlresidencysetdescriptor.md)