// ObjectiveC/ObjectiveC.swift
public func autoreleasepool<E, Result: ~Copyable>(
    invoking body: () throws(E) -> Result
) throws(E) -> Result {
    // 1. 进入作用域：向 objc runtime 要一个池 token。
    //    token 不是池对象，而是当前栈中 POOL_BOUNDARY 的地址。
    let pool = _autoreleasePoolPush()

    // 2. 无论 body 正常返回还是抛错，都必须 pop。
    //    这就是 @autoreleasepool 的作用域语义。
    defer {
        _autoreleasePoolPop(pool)
    }

    // 3. body 期间产生的 autorelease 对象会登记到当前线程的池栈。
    return try body()
}
```text

来源：`ObjectiveC/ObjectiveC.swift:185`

### 运行时 API 入口

C API 很薄，只是把工作转交给 `AutoreleasePoolPage`。

``` cpp
// runtime/NSObject.mm
void *objc_autoreleasePoolPush(void)
{
    // push() 会压入 POOL_BOUNDARY，并返回边界槽位地址。
    // 调用者必须保存这个地址，后续 pop 依赖它确定释放范围。
    return AutoreleasePoolPage::push();
}

void objc_autoreleasePoolPop(void *ctxt)
{
    // ctxt 就是 push 返回的 token。
    // pop() 会校验 token，然后释放 token 之上的对象。
    AutoreleasePoolPage::pop(ctxt);
}

id objc_autorelease(id obj)
{
    // nil 和 tagged pointer 不需要引用计数管理。
    if (_objc_isTaggedPointerOrNil(obj)) return obj;

    // 进入 objc_object::autorelease()，可能走默认实现，
    // 也可能通过 objc_msgSend 调用类自定义的 -autorelease。
    return obj->autorelease();
}
```text

来源：`runtime/NSObject.mm:2013`、`runtime/NSObject.mm:2256`

### 数据结构：一页就是一段指针栈

``` cpp
// runtime/NSObject-internal.h
struct AutoreleasePoolPageData
{
    magic_t const magic;            // 页完整性检查，调试坏 token 或越界写。
    __unsafe_unretained id *next;   // 下一个可写槽位，也就是栈顶后一格。
    objc_thread_t const thread;     // 该页归属线程，防止跨线程误用。
    AutoreleasePoolPage * const parent;
    AutoreleasePoolPage *child;     // 多页串成链表，parent 更冷，child 更热。
    uint32_t const depth;           // 页深度，用于统计和高水位日志。
    uint32_t hiwat;                 // high-water mark，用于诊断池过大。
};
```text

来源：`runtime/NSObject-internal.h:133`

页头之后的内存就是对象槽位。`begin()` 指向第一个槽位， `end()` 指向页尾，`next == begin()` 表示空页。

### push：压入边界，返回 token

``` cpp
// runtime/NSObject.mm
static inline void *push()
{
    // 返回值优化可能把对象临时放在 TLS 中。
    // push 新池前先把它转移到真实池里，避免遗留对象漏掉。
    ReturnAutoreleaseInfo info = getReturnAutoreleaseInfo();
    moveTLSAutoreleaseToPool(info);

    id *dest;
    if (slowpath(DebugPoolAllocation)) {
        // 调试模式：每个 pool 单独开新页，方便定位问题。
        dest = autoreleaseNewPage(POOL_BOUNDARY);
    } else {
        // 正常模式：像普通对象一样把边界压到 hot page。
        dest = autoreleaseFast(POOL_BOUNDARY);
    }

    // dest 是 POOL_BOUNDARY 的槽位地址。
    // 这个地址就是 pop() 需要的 token。
    return dest;
}
```text

来源：`runtime/NSObject.mm:1246`

### autorelease：快路径追加对象

``` cpp
// runtime/NSObject.mm
static inline id *autoreleaseFast(id obj)
{
    AutoreleasePoolPage *page = hotPage();

    if (page && !page->full()) {
        // 最常见路径：当前线程已经有 hot page，且页未满。
        // 直接把 obj 写入 *next，然后 next++。
        return page->add(obj);
    } else if (page) {
        // 有 hot page，但满了：沿 child 找可用页，没有就创建新页。
        return autoreleaseFullPage(obj, page);
    } else {
        // 没有任何 page：可能是首次 push，也可能缺少 pool。
        return autoreleaseNoPage(obj);
    }
}

id *add(id obj)
{
    id *ret = next;     // 记录本次写入槽位，push 会把它作为 token。
    *next++ = obj;      // 栈追加。obj 可以是真对象，也可以是 POOL_BOUNDARY。
    return ret;
}
```cpp

来源：`runtime/NSObject.mm:907`、`runtime/NSObject.mm:1113`

### objc_object::autorelease：是否允许自定义

``` cpp
// runtime/objc-object.h
inline id objc_object::autorelease()
{
    if (isTaggedPointer()) return (id)this;

    if (fastpath(!ISA()->hasCustomRR())) {
        // 类没有自定义 retain/release/autorelease。
        // 直接走 runtime 默认实现，避免一次 objc_msgSend。
        return rootAutorelease();
    }

    // 类自定义了 RR 行为时，必须尊重它的 -autorelease。
    return ((id(*)(objc_object *, SEL))objc_msgSend)
        (this, @selector(autorelease));
}

ALWAYS_INLINE id objc_object::rootAutorelease()
{
    // 默认实现还会尝试“返回值 autorelease 优化”。
    if (prepareOptimizedReturn((id)this, true, ReturnAtPlus1))
        return (id)this;

    // 优化失败才真正进入 AutoreleasePoolPage。
    return rootAutorelease2();
}
```text

来源：`runtime/objc-object.h:1258`

### pop：定位边界并释放到边界

``` cpp
// runtime/NSObject.mm
static inline void pop(void *token)
{
    // 先处理返回值优化 TLS 中尚未落入真实池的对象。
    while (releaseReturnAutoreleaseTLS())
        ;

    AutoreleasePoolPage *page;
    if (token == (void*)EMPTY_POOL_PLACEHOLDER) {
        // 顶层空池优化：池从未放入对象时甚至不分配真实 page。
        page = hotPage();
        if (!page) return setHotPage(nil);
        page = coldPage();
        token = page->begin();
    } else {
        // token 是 POOL_BOUNDARY 槽位地址。
        // 通过地址按页大小对齐，反推出它所在的 AutoreleasePoolPage。
        page = pageForPointer(token);
    }

    id *stop = (id *)token;
    if (*stop != POOL_BOUNDARY) {
        // token 无效或池被提前释放，运行时会报错或 fatal。
        return badPop(token);
    }

    // 释放 stop 之上的所有对象，stop 自身是边界，不释放。
    return popPage<false>(token, page, stop);
}
```text

来源：`runtime/NSObject.mm:1326`

### releaseUntil：后进先出释放

``` cpp
// runtime/NSObject.mm
void releaseUntil(id *stop)
{
    do {
        while (this->next != stop) {
            // 每轮都重新读取 hotPage。
            // 原因：objc_release(obj) 可能触发 dealloc，
            // dealloc 里又可能 autorelease 新对象或 push 新池。
            AutoreleasePoolPage *page = hotPage();

            while (page->empty()) {
                page = page->parent;
                setHotPage(page);
            }

            // 从栈顶取出一个槽位：先 --next，再读对象。
            id obj = *--page->next;
            memset((void*)page->next, SCRIBBLE, sizeof(*page->next));

            // 边界只用于分隔，不是对象。
            if (obj != POOL_BOUNDARY) {
                objc_release(obj);
            }
        }

        // TLS 中概念上也可能有一个“待 autorelease”对象。
        // 释放它后可能产生更多 autorelease，所以用 do-while。
    } while (releaseReturnAutoreleaseTLS());

    setHotPage(this);
}
```text

来源：`runtime/NSObject.mm:976`

## 返回值 autorelease 优化

Cocoa 有大量“返回 +0 autoreleased 对象”的调用。如果每次都先 autorelease 到池里，调用者再 retain， 就会产生一对多余操作。objc4 用 `ReturnAutoreleaseInfo` TLS 做 callee/caller 交接： callee 发现 caller 会立刻 claim 这个返回值时，把对象和当前引用计数状态放进 TLS，不进池； caller 读取 TLS 后按自己需要接收 +0 或 +1。交接失败时，再把对象转回真实 autorelease pool。

``` cpp
// runtime/NSObject.mm
id objc_autoreleaseReturnValue(id obj)
{
    // callee 端：对象当前是 +1，但函数签名要按 +0 autoreleasing 返回。
    // 如果 caller 是可优化形态，就把 obj 记录到 ReturnAutoreleaseInfo TLS，
    // 不把它放进 AutoreleasePoolPage。
    if (prepareOptimizedReturn(obj, false, ReturnAtPlus1)) return obj;

    // caller 不配合时，走普通路径：登记到 autorelease pool。
    return objc_autorelease(obj);
}

id objc_retainAutoreleasedReturnValue(id obj)
{
    // caller 端：希望把 +0 返回值变成 +1。
    // 如果 TLS 证明 callee 已经把 +1 对象交给我们，就不需要 retain。
    if (acceptOptimizedReturn(true) == ReturnAtPlus1) return obj;

    // 未优化路径中，返回值按 +0 处理，需要 retain 才能拥有。
    return objc_retain(obj);
}
```cpp

来源：`runtime/NSObject.mm:2310`、`runtime/NSObject.mm:2337`

这类优化不改变语义。你仍然可以按“autorelease 会在池 pop 时 release”理解程序行为，只是运行时在安全时把部分登记和释放省掉了。

### 常见误区

- `autorelease` 不会立刻释放对象，它只是安排未来 release。
- `@autoreleasepool` 不是 Objective-C 对象容器，运行时 token 只是边界地址。
- 对象在池中不被 retain。autorelease 的前提通常是对象当前已有 +1 所有权，稍后由池帮你 release。
- 池是线程私有的，一个线程 autorelease 的对象不会被另一个线程的 pool 接管。
- 缺少 pool 时，调试开关可以报警；正常程序应在线程入口或密集循环中主动设置 pool。

### 读源码时抓这条主线

1.  `objc_autorelease(obj)` 进入 `objc_object::autorelease()`。
2.  默认 RR 类走 `rootAutorelease()`，先尝试返回值优化。
3.  优化失败进入 `rootAutorelease2()`，调用 `AutoreleasePoolPage::autorelease()`。
4.  `autoreleaseFast()` 把对象写入 TLS hot page。
5.  `objc_autoreleasePoolPop(token)` 调用 `releaseUntil(token)`，逐个 `objc_release`。

## 一个最小例子

``` objc
@autoreleasepool {
    id obj = [[[MyObject alloc] init] autorelease];
    // alloc/init 产生 +1 所有权。
    // autorelease 不改变 obj 现在可用这个事实，只是把一次 release 推迟到 pool pop。

    use(obj);
    // 这里 obj 仍然有效，因为 pool 还没有 pop。
}
// 离开作用域时编译器生成 objc_autoreleasePoolPop(token)。
// runtime 从栈顶释放到该 token，obj 收到 release。
// 如果这是最后一个引用，obj 在这里 dealloc。