Managing Metal Cpp Lifetimes

---
name: managing-metal-cpp-lifetimes
description: ALWAYS use when writing or porting Metal object lifetime management code in metal-cpp — including crashes on release, use-after-free, memory leaks, autorelease pool placement, NS::TransferPtr vs NS::RetainPtr ownership, bridge casts at ARC/metal-cpp boundaries, or any question about when and how Metal objects are retained, released, or destroyed.
---

# Metal C/C++ Lifetime Management

metal-cpp types like `MTL::Buffer*` wrap ObjC Metal objects, so the underlying ObjC retain/release rules still apply. Getting ownership wrong causes leaks, use-after-free, or double-free.

## Ownership Decision (metal-cpp)

Methods starting with `new`, `alloc`, `copy`, `mutableCopy`, or `Create` return **owned** (+1) objects. Everything else returns **autoreleased** objects.

```
Returned from new/alloc/copy/mutableCopy/Create?
  YES → NS::TransferPtr(ptr)          // you already own it
  NO  → need AutoreleasePool in scope
        Want to keep beyond pool scope?
          YES → NS::RetainPtr(ptr)     // retains; survives pool drain
          NO  → use raw pointer        // pool drains it
```

### Quick Reference

| API Pattern | Returns | Wrap With |