목차

1. TL;DR — 한눈에 보는 4가지 규칙
2. 비유로 먼저 이해하기 — 식당 주방의 4가지 규칙
3. 규칙 ① I/O는 `async`, CPU 바인드 작업은 `Task.Run`
4. 규칙 ② `async void`는 이벤트 핸들러에서만
5. 규칙 ③ `await` 앞뒤에서 예외가 어떻게 전파되는지 항상 확인
6. 규칙 ④ 공유 상태는 피하고, 불가피하면 `lock` 또는 불변 데이터로 감싸기
7. 4가지 규칙 위반 자가 진단표
8. PART 13 학습 회고
9. 마무리 한 줄

// 안티패턴 1: I/O 작업을 Task.Run으로 이중 포장 — 스레드 풀 낭비
public Task<string> FetchUserAsync(string id)
{
    var http = new HttpClient();
    return Task.Run(() => http.GetStringAsync($"/users/{id}"));
    //     ^^^^^^^^^ GetStringAsync는 이미 비동기 I/O다.
    //     Task.Run은 스레드 풀 스레드 1개를 잡아서 await만 시키고 있음.
}

// 안티패턴 2: CPU 작업을 await로만 감쌌지만 사실은 동기
public async Task<int> ComputeChecksumAsync(byte[] data)
{
    int sum = 0;
    for (int i = 0; i < data.Length; i++) sum += data[i] * 31;
    // await 한 번도 없음 → 호출 스레드가 그대로 점유됨
    // 메인 스레드에서 호출하면 UI 프리징
    return sum;
}

// I/O 바인드: GetStringAsync 자체가 비동기. Task.Run 불필요
public async Task<string> FetchUserAsync(string id)
{
    using var http = new HttpClient();
    return await http.GetStringAsync($"/users/{id}");
}

// CPU 바인드: 호출 측에서 Task.Run으로 위임
public Task<int> ComputeChecksumAsync(byte[] data)
{
    return Task.Run(() =>
    {
        int sum = 0;
        for (int i = 0; i < data.Length; i++) sum += data[i] * 31;
        return sum;
    });
}

public class OrderService
{
    // 안티패턴: 일반 메서드를 async void로 선언
    public async void SaveOrderAsync(Order order)
    {
        await _db.InsertAsync(order);
        if (order.Total < 0)
            throw new InvalidOperationException("Total < 0");
            // 이 예외는 호출자가 잡을 수 없다.
            // 앱이 그냥 죽는다.
    }
}

// 호출 측 — 잡으려고 해도 잡히지 않음
public void Process(Order order)
{
    try
    {
        _service.SaveOrderAsync(order); // await 못 함, Task가 없음
    }
    catch (Exception)
    {
        // 절대 실행되지 않음
    }
}

public class OrderService
{
    // 일반 메서드는 Task 반환
    public async Task SaveOrderAsync(Order order)
    {
        await _db.InsertAsync(order);
        if (order.Total < 0)
            throw new InvalidOperationException("Total < 0");
    }
}

// 이벤트 핸들러만 async void 허용
public partial class OrderForm : Form
{
    private async void SaveButton_Click(object sender, EventArgs e)
    {
        try
        {
            await _service.SaveOrderAsync(_currentOrder);
            MessageBox.Show("저장 완료");
        }
        catch (InvalidOperationException ex)
        {
            MessageBox.Show($"저장 실패: {ex.Message}");
        }
    }
}

// async Task — 빌더가 예외를 Task에 캡처
[AsyncStateMachine(typeof(StateMachine_Task))]
public Task DoWorkAsync() { /* ... */ }

// async void — 빌더가 예외를 SynchronizationContext로 던짐
[AsyncStateMachine(typeof(StateMachine_Void))]
public void DoWorkAsync() { /* ... */ }

// Unity에서 안전한 진입 패턴
private void Start()
{
    _ = StartCoreAsync(); // 또는 별도 헬퍼로 예외 로깅
}

private async Task StartCoreAsync()
{
    try
    {
        await LoadAssetsAsync();
        await ConnectToServerAsync();
    }
    catch (Exception ex)
    {
        Debug.LogException(ex); // 최소한 로그는 남는다
    }
}

// 안티패턴 1: await 누락 — 예외가 잡히지 않음
public async Task RunAsync()
{
    try
    {
        FetchAsync(); // await 빠짐
    }
    catch (HttpRequestException)
    {
        // 절대 실행되지 않음
    }
}

// 안티패턴 2: .Result / .Wait()로 동기 차단 — UI 데드락
public string GetUserSync()
{
    return FetchUserAsync().Result;
    // UI 스레드에서 호출 시 데드락
    // 예외도 AggregateException으로 한 겹 더 감싸짐
}

// 안티패턴 3: WhenAll 결과를 try/catch로만 감쌌지만, 첫 예외만 잡음
public async Task RunAllAsync(List<Task> tasks)
{
    try
    {
        await Task.WhenAll(tasks);
    }
    catch (Exception ex)
    {
        // 여러 Task가 동시에 예외를 던졌을 때
        // 그중 첫 번째 예외만 잡힘 (나머지는 Task.Exception에 그대로 남음)
        Console.WriteLine(ex.Message);
    }
}

// 1) await로 예외를 정상 풀어내기
public async Task RunAsync()
{
    try
    {
        await FetchAsync();
    }
    catch (HttpRequestException ex)
    {
        Console.WriteLine($"네트워크 오류: {ex.Message}");
    }
}

// 2) Result/Wait 절대 금지 — 끝까지 await로 가져가기
public async Task<string> GetUserAsync()
{
    return await FetchUserAsync();
}

// 3) WhenAll의 모든 예외를 보려면 Task의 Exception 직접 확인
public async Task RunAllAsync(List<Task> tasks)
{
    var whenAll = Task.WhenAll(tasks);
    try
    {
        await whenAll;
    }
    catch
    {
        // 모든 예외 수집
        if (whenAll.Exception is { } agg)
        {
            foreach (var inner in agg.Flatten().InnerExceptions)
                Console.WriteLine($"[실패] {inner.Message}");
        }
        throw;
    }
}

private int _counter = 0;
private readonly object _gate = new();

// 안티패턴 1: lock 없이 공유 상태 수정
public async Task UnsafeIncrementAsync()
{
    int t = _counter;
    await Task.Delay(10);  // 여기서 다른 Task가 끼어들 수 있음
    _counter = t + 1;       // → 카운트 누락
}

// 안티패턴 2: lock 안에서 await — 컴파일 에러
public async Task InvalidLockAsync()
{
    lock (_gate)
    {
        await Task.Delay(10); // CS1996
        _counter++;
    }
}

// 안티패턴 3: ConcurrentDictionary로 안심하다가 "Read-Modify-Write" 실수
private ConcurrentDictionary<string, int> _scores = new();
public void AddScore(string user, int delta)
{
    var current = _scores.GetValueOrDefault(user, 0); // 1) 읽기
    _scores[user] = current + delta;                   // 2) 쓰기
    // 1과 2 사이에 다른 스레드가 끼어들면 값 손실
}

// 1) 비동기 안에서 락이 필요하면 SemaphoreSlim
private readonly SemaphoreSlim _gate = new(1, 1);
private int _counter = 0;

public async Task SafeIncrementAsync()
{
    await _gate.WaitAsync();
    try
    {
        int t = _counter;
        await Task.Delay(10);
        _counter = t + 1;
    }
    finally
    {
        _gate.Release();
    }
}

// 2) 단순 카운터는 Interlocked로 락-프리
private long _hits;
public void IncrementHits() => Interlocked.Increment(ref _hits);

// 3) ConcurrentDictionary는 AddOrUpdate로 원자적 수정
private ConcurrentDictionary<string, int> _scores = new();
public void AddScore(string user, int delta)
{
    _scores.AddOrUpdate(user, delta, (_, prev) => prev + delta);
}

// 4) 가장 안전한 길 — 불변 데이터로 만들기
public sealed record GameState(int Score, int Lives, ImmutableList<Item> Items);

// 상태를 바꿀 때마다 새 객체를 만들고 참조만 교체
private GameState _state = new(0, 3, ImmutableList<Item>.Empty);
public void AddItem(Item item)
{
    var snapshot = _state;
    var next = snapshot with { Items = snapshot.Items.Add(item) };
    Interlocked.CompareExchange(ref _state, next, snapshot);
}

// 원본
lock (_gate) { Critical(); }

// 컴파일러가 생성하는 IL 의사코드
bool taken = false;
try
{
    Monitor.Enter(_gate, ref taken);
    Critical();
}
finally
{
    if (taken) Monitor.Exit(_gate);
}

목차

1. 한 줄 요약
2. 왜 멀티스레딩에서 결과가 어긋날까
3. 비유로 잡기
4. 코드로 감 잡기 — 경쟁 상태 재현과 방어
5. 데드락 — 멈춰서 안 풀리는 상태
6. 예방 규칙 세 가지 — "감 잡기" 단계에서 이것만 지켜도 80%
7. Unity 입문자가 만나기 쉬운 함정
8. 한눈 비교 — `Interlocked` vs `lock`
9. 심화 커리큘럼 (이 글의 범위 밖)
10. 정리

using System;
using System.Threading;
using System.Threading.Tasks;

class RaceDemo
{
    static int counter = 0;

    static void Main()
    {
        // 두 스레드가 각각 100,000번씩 ++ → 기대값 200,000
        Parallel.Invoke(
            () => { for (int i = 0; i < 100_000; i++) counter++; },
            () => { for (int i = 0; i < 100_000; i++) counter++; }
        );

        Console.WriteLine($"실제: {counter} / 기대: 200,000");
    }
}

static int counter = 0;

Parallel.Invoke(
    () => { for (int i = 0; i < 100_000; i++) Interlocked.Increment(ref counter); },
    () => { for (int i = 0; i < 100_000; i++) Interlocked.Increment(ref counter); }
);

Console.WriteLine($"실제: {counter}"); // 항상 200,000

class Wallet
{
    private readonly object _gate = new();      // 락 전용 객체
    private int _krw;
    private int _coin;

    public void Exchange(int krwIn, int coinOut)
    {
        // 두 변수의 변경이 "동시에" 일어난 것처럼 보여야 합니다.
        lock (_gate)
        {
            _krw -= krwIn;
            _coin += coinOut;
        }
    }
}

bool taken = false;
try
{
    Monitor.Enter(_gate, ref taken);
    _krw -= krwIn;
    _coin += coinOut;
}
finally
{
    if (taken) Monitor.Exit(_gate);
}

using System.Threading;

class DeadlockDemo
{
    static readonly object lockA = new();
    static readonly object lockB = new();

    static void Main()
    {
        var t1 = new Thread(() =>
        {
            lock (lockA)
            {
                Thread.Sleep(50);          // 상대가 lockB 를 잡을 시간 확보
                lock (lockB) { /* unreached */ }
            }
        });

        var t2 = new Thread(() =>
        {
            lock (lockB)
            {
                Thread.Sleep(50);
                lock (lockA) { /* unreached */ }
            }
        });

        t1.Start(); t2.Start();
        t1.Join();  t2.Join();              // 영원히 안 끝남
    }
}

// t2 의 락 순서를 t1 과 같게 맞춤
var t2 = new Thread(() =>
{
    lock (lockA)        // 먼저 lockA
    {
        Thread.Sleep(50);
        lock (lockB) { /* ok */ }
    }
});

// 두 계좌를 동시에 잠가야 할 때 — ID 작은 쪽부터
public static void Transfer(Account from, Account to, int amount)
{
    var (first, second) = from.Id < to.Id ? (from, to) : (to, from);
    lock (first.Gate)
    lock (second.Gate)
    {
        from.Balance -= amount;
        to.Balance   += amount;
    }
}

// ❌ 위험 — 락 안에서 콜백 호출
lock (_gate)
{
    _items.Add(item);
    OnItemAdded?.Invoke(item);   // 구독자가 또 다른 락을 잡으면? 데드락 가능성
}

// ✅ 안전 — 락 밖으로 빼고 발행
ItemAddedEvent? toRaise = null;
lock (_gate)
{
    _items.Add(item);
    toRaise = OnItemAdded;
}
toRaise?.Invoke(item);

// ❌ 락 안에서 무거운 작업
lock (_gate)
{
    var json = JsonSerializer.Serialize(_state);   // CPU 무거움
    File.WriteAllText("dump.json", json);          // I/O — 절대 락 안에서 X
}

// ✅ 스냅샷만 락 안에서 만들고 락 밖에서 처리
State snapshot;
lock (_gate)
{
    snapshot = _state.Clone();
}
var json = JsonSerializer.Serialize(snapshot);
File.WriteAllText("dump.json", json);

목차

1. 왜 새 타입이 필요했는가 — `lock(object)` 의 구조적 부담
2. 30초 요약 — 한 줄만 바꾸면 됩니다
3. ADEPT — 비유로 이해하는 `Lock` vs `lock(object)`
4. IL 로 직접 확인하기 — 두 코드는 정말 다른 IL 로 컴파일됩니다
5. `Lock.EnterScope()` 와 `ref struct Scope` — 왜 굳이 ref struct 인가
6. 함정 — `object` 캐스팅·할당 시 새 API 가 사라진다
7. `using` 패턴으로 명시적으로 쓰기
8. `TryEnter` — 시간 제한이 있는 락 시도
9. 마이그레이션 가이드 — 점진적으로 옮기기
10. Unity 환경에서의 주의
11. 자주 묻는 질문
12. 정리
13. 참고 자료

// Before (.NET 8 이하 / 고전 패턴)
private readonly object _sync = new();

public void Increment()
{
    lock (_sync)            // → Monitor.Enter / Monitor.Exit 로 변환
    {
        _count++;
    }
}

// After (.NET 9 / C# 13)
private readonly System.Threading.Lock _sync = new();

public void Increment()
{
    lock (_sync)            // → _sync.EnterScope() + Scope.Dispose() 로 변환
    {
        _count++;
    }
}

using System.Threading;

public sealed class Counter
{
    private readonly Lock _sync = new();
    private int _count;

    public void Increment()
    {
        lock (_sync)
        {
            _count++;
        }
    }

    public int Read()
    {
        lock (_sync)
        {
            return _count;
        }
    }
}

public sealed class CounterObject
{
    private readonly object _sync = new();
    private int _count;

    public void Increment()
    {
        lock (_sync) { _count++; }
    }
}

.method public hidebysig instance void Increment() cil managed
{
    .locals init (object V_0, bool V_1)
    ldarg.0
    ldfld      object CounterObject::_sync
    stloc.0
    ldc.i4.0
    stloc.1
    .try
    {
        ldloc.0
        ldloca.s   V_1
        call       void [System.Threading]System.Threading.Monitor::Enter(object, bool&)
        // _count++
        ldarg.0
        dup
        ldfld      int32 CounterObject::_count
        ldc.i4.1
        add
        stfld      int32 CounterObject::_count
        leave.s    EndFinally
    }
    finally
    {
        ldloc.1
        brfalse.s  EndOfFinally
        ldloc.0
        call       void [System.Threading]System.Threading.Monitor::Exit(object)
        EndOfFinally: endfinally
    }
    EndFinally: ret
}

public sealed class CounterLock
{
    private readonly System.Threading.Lock _sync = new();
    private int _count;

    public void Increment()
    {
        lock (_sync) { _count++; }
    }
}

.method public hidebysig instance void Increment() cil managed
{
    .locals init (valuetype [System.Threading]System.Threading.Lock/Scope V_0)
    ldarg.0
    ldfld      class [System.Threading]System.Threading.Lock CounterLock::_sync
    callvirt   instance valuetype [System.Threading]System.Threading.Lock/Scope
               [System.Threading]System.Threading.Lock::EnterScope()
    stloc.0
    .try
    {
        ldarg.0
        dup
        ldfld      int32 CounterLock::_count
        ldc.i4.1
        add
        stfld      int32 CounterLock::_count
        leave.s    EndFinally
    }
    finally
    {
        ldloca.s   V_0
        call       instance void
                   [System.Threading]System.Threading.Lock/Scope::Dispose()
        endfinally
    }
    EndFinally: ret
}

namespace System.Threading;

public sealed class Lock
{
    public Scope EnterScope();          // ⬅ ref struct 반환
    public bool TryEnter();
    public bool TryEnter(int millisecondsTimeout);
    public bool TryEnter(TimeSpan timeout);
    public void Enter();
    public void Exit();
    public bool IsHeldByCurrentThread { get; }

    public ref struct Scope             // ⬅ ref struct
    {
        public void Dispose();
    }
}

// ✗ 컴파일 에러: ref struct 는 필드로 저장 불가
class Holder
{
    Lock.Scope _s;
}

// ✗ 컴파일 에러: ref struct 는 await 경계를 넘을 수 없음
async Task Bad()
{
    using (var s = _lock.EnterScope())
    {
        await Task.Delay(100);   // CS4007 / CS8350 류 에러
        // 만약 허용되면 await 후 다른 스레드에서 Dispose 가 호출될 수 있음
    }
}

// ✗ 람다 캡처 불가
Action a = () =>
{
    using (var s = _lock.EnterScope())   // s 는 캡처 가능한 일반 변수지만
    {
        // 람다 외부로 새어 나갈 수 없음 (ref struct 제약)
    }
};

private readonly Lock _sync = new();

void Case1()
{
    lock (_sync) { /* OK — 새 API */ }
}

void Case2()
{
    object boxed = _sync;
    lock (boxed) { /* ✗ 새 API 아님 — boxed 의 정적 타입이 object */ }
}

void Case3()
{
    lock ((object)_sync) { /* ✗ 새 API 아님 — 캐스트로 정적 타입이 object */ }
}

void Case4(object o)
{
    lock (o) { /* ✗ 새 API 아님 — 매개변수 타입이 object */ }
}

// ✗ 폴백 함정
static void RunUnderLock(object lockObj, Action body)
{
    lock (lockObj) { body(); }   // lockObj 정적 타입은 object
}

// ✓ Lock 인지 그대로 유지
static void RunUnderLock(Lock lockObj, Action body)
{
    lock (lockObj) { body(); }   // 새 API 로 변환됨
}

public int ReadCount()
{
    using Lock.Scope scope = _sync.EnterScope();
    return _count;
}

public void Update(Func<int, int> update)
{
    using (_sync.EnterScope())
    {
        _count = update(_count);
    }
}

private readonly Lock _sync = new();

public bool TryUpdate(Action body, TimeSpan timeout)
{
    if (!_sync.TryEnter(timeout))
        return false;

    try
    {
        body();
        return true;
    }
    finally
    {
        _sync.Exit();
    }
}

목차

1. [문제 제기] `_counter++` 한 줄이 어떻게 값을 잃어버리는가
2. [개념 정의] 임계 구역 · 상호 배제 · Monitor
3. [작동 원리] `lock`은 `try/finally`로 감싼 `Monitor.Enter`/`Exit`다 — IL로 직접 본다
4. [락 객체 선택의 규칙] 왜 `private readonly object`인가
5. [락 안에서 await 금지] 스레드 소유권이라는 모델
6. [데드락] 두 락을 다른 순서로 잡으면 영원히 풀리지 않는다
7. [성능 특성] 무경합은 매우 싸고, 경합은 점점 비싸진다
8. [Unity 실전 패턴] 메인 스레드 모델과 lock의 사용처
9. [다른 동기화 도구와의 비교] lock이 답이 아닌 경우
10. [자주 하는 실수와 해법]
11. [버전별 변화]
12. [요약]

public class DownloadProgress
{
    private int _completed;

    public void OnAssetCompleted()
    {
        _completed++; // 한 줄이지만 안전하지 않습니다.
    }

    public int GetCompleted() => _completed;
}

public class Counter
{
    private readonly object _sync = new();
    private int _value;

    public void Increment()
    {
        lock (_sync)
        {
            _value++;
        }
    }
}

public void Increment()
{
    object obj = _sync;
    bool lockTaken = false;
    try
    {
        Monitor.Enter(obj, ref lockTaken);
        _value++;
    }
    finally
    {
        if (lockTaken) Monitor.Exit(obj);
    }
}

.method public hidebysig instance void Increment () cil managed
{
    .locals init (
        [0] object obj,
        [1] bool lockTaken)

    // obj = this._sync
    ldarg.0
    ldfld      object Counter::_sync
    stloc.0

    // lockTaken = false
    ldc.i4.0
    stloc.1
    .try
    {
        // Monitor.Enter(obj, ref lockTaken)
        ldloc.0
        ldloca.s   lockTaken
        call       void [System.Threading]System.Threading.Monitor::Enter(object, bool&)

        // _value++
        ldarg.0
        dup
        ldfld      int32 Counter::_value
        ldc.i4.1
        add
        stfld      int32 Counter::_value

        leave.s    END
    }
    finally
    {
        // if (lockTaken) Monitor.Exit(obj)
        ldloc.1
        brfalse.s  EXIT
        ldloc.0
        call       void [System.Threading]System.Threading.Monitor::Exit(object)
        EXIT: endfinally
    }
    END: ret
}

lock (this)                  { /* ... */ }   // ❌ 위험
lock (typeof(MyClass))       { /* ... */ }   // ❌ 위험
lock ("global_lock")         { /* ... */ }   // ❌❌ 매우 위험
lock (_publicField)          { /* ... */ }   // ❌ 위험
lock (_privateReadonlyObj)   { /* ... */ }   // ✓ 권장

public class Cache
{
    public void Refresh() { lock (this) { /* ... */ } } // 내부적으로 this 잠금
}

// 어딘가의 외부 코드
var cache = container.GetCache();
lock (cache) { Thread.Sleep(10000); } // 같은 객체를 외부가 10초 점유
// 이 사이 cache.Refresh()는 모두 블록됨 — 락 탈취(lock hijacking)

class Foo
{
    public static void Op1() { lock (typeof(Foo)) { /* ... */ } } // 같은 Type을 잡음
}

class Bar  // 완전히 다른 클래스, 같은 라이브러리도 아님
{
    public static void Op2() { lock (typeof(Foo)) { /* ... */ } } // 같은 Type을 잡음
}

// 두 메서드, 두 라이브러리에 흩어져 있음
void A() { lock ("global_lock") { /* ... */ } }
void B() { lock ("global_lock") { /* ... */ } }

int x = 42;
lock (x) { /* ... */ } // 컴파일 에러 CS0185: 'lock' 문에 사용된 식은 참조 형식이어야 합니다.

async Task FetchAndStore()
{
    lock (_sync)
    {
        await SomeApiAsync(); // ❌ CS1996: 'lock' 문 본문에서는 await을 사용할 수 없습니다.
        _cache = result;
    }
}

public class AsyncCache
{
    private readonly SemaphoreSlim _gate = new(1, 1); // 카운트 1 = 사실상 mutex
    private string? _cached;

    public async Task<string> GetAsync(CancellationToken ct = default)
    {
        await _gate.WaitAsync(ct);   // ✓ 비동기 진입
        try
        {
            _cached ??= await FetchFromApiAsync(ct); // ✓ 안에서 await 가능
            return _cached;
        }
        finally
        {
            _gate.Release();
        }
    }
}

private readonly object _lockA = new();
private readonly object _lockB = new();

void Worker1()
{
    lock (_lockA)
    {
        Thread.Sleep(10);   // Worker2가 _lockB 잡을 시간 확보
        lock (_lockB) { /* ... */ }  // _lockA 가진 채 _lockB를 기다림
    }
}

void Worker2()
{
    lock (_lockB)
    {
        Thread.Sleep(10);
        lock (_lockA) { /* ... */ }  // _lockB 가진 채 _lockA를 기다림
    }
}

void Worker1() {
    lock (_lockA) lock (_lockB) { /* ... */ }   // A → B
}
void Worker2() {
    lock (_lockA) lock (_lockB) { /* ... */ }   // A → B (순서 통일)
}

bool taken = false;
try
{
    Monitor.TryEnter(_sync, TimeSpan.FromSeconds(2), ref taken);
    if (!taken)
    {
        Debug.LogWarning("락 획득 실패 — 데드락 의심, 자원 반납");
        return;  // 다른 락도 풀고 후퇴 → 데드락 회피
    }
    // 임계 구역
}
finally
{
    if (taken) Monitor.Exit(_sync);
}

public class MainThreadDispatcher : MonoBehaviour
{
    private static MainThreadDispatcher _instance;
    private readonly Queue<Action> _queue = new();
    private readonly object _sync = new();

    public static void Enqueue(Action action)
    {
        // 어느 스레드에서 호출되든 안전해야 함
        lock (_instance._sync)
        {
            _instance._queue.Enqueue(action);
        }
    }

    private void Update()
    {
        // 매 프레임 메인 스레드에서 한 번씩 비웁니다
        while (true)
        {
            Action next;
            lock (_sync)
            {
                if (_queue.Count == 0) return;
                next = _queue.Dequeue();
            }
            // ⚠ 락 밖에서 실행 — 콜백이 다시 Enqueue를 호출해도 데드락 없음
            try { next(); }
            catch (Exception e) { Debug.LogException(e); }
        }
    }
}

public class ResultPool<T> where T : new()
{
    private readonly Stack<T> _stack = new();
    private readonly object _sync = new();

    public T Rent()
    {
        lock (_sync)
        {
            if (_stack.Count > 0) return _stack.Pop();
        }
        // 락 밖에서 new — 객체 생성 비용이 락 점유 시간에 끼지 않음
        return new T();
    }

    public void Return(T item)
    {
        lock (_sync) { _stack.Push(item); }
    }
}

public class LogBuffer
{
    private readonly Queue<string> _queue = new();
    private readonly object _sync = new();

    public void Add(string line)
    {
        lock (_sync) { _queue.Enqueue(line); }    // 짧다
    }

    public string[] Drain()
    {
        lock (_sync)
        {
            if (_queue.Count == 0) return Array.Empty<string>();
            var arr = _queue.ToArray();
            _queue.Clear();
            return arr;
        }
    }
}

// ❌ 메인 스레드 객체를 백그라운드에서 lock으로 보호한다고 안전해지지 않음
lock (_sync) { transform.position = newPos; }
// → Unity는 transform 접근 자체를 메인 스레드에서만 허용. lock으로는 풀리지 않음.

// ❌ static 라이브러리(예: Resources)를 lock으로 직접 보호
lock (typeof(Resources)) { ... }
// → Resources는 Unity 내부에서 자체 동기화. 외부 lock은 의미 없고 데드락 위험만 큼.

// ❌ Coroutine 안에서 lock 잡고 yield return WaitForSeconds
IEnumerator Foo() {
    lock (_sync) {
        yield return new WaitForSeconds(1); // ← yield는 컴파일러에서 메서드를 쪼갠다.
    }                                       //    yield 이후 부분은 다음 프레임에 다시 호출되며,
}                                           //    그 사이 lock 상태는 정의되지 않음. 사실상 await의 친척.

목차

1. [문제 제기] 1만 건의 로그를 모두 메모리에 올리고 시작할 것인가
2. [개념 정의] 비동기 Pull 모델 — 한 건씩 당겨오는 스트림
3. [내부 동작] 컴파일러가 만드는 상태머신 — `MoveNextAsync()`와 `Current`
4. [실전 적용] Before/After — Unity 핫패스에서 메모리·반응성 모두 잡기
5. [함정과 주의사항] 신입이 자주 틀리는 4가지
6. [C# 버전별 변화] C# 8 도입부터 .NET 9까지
7. [정리] 비동기 스트림 핵심 체크리스트

// Unity 화면: "로그 보기" 버튼을 누르면 로그를 가져와 표시
public async Task LoadLogsAsync()
{
    List<string> lines = await ReadAllLinesAsync(path); // 1만 줄을 한꺼번에 List에 담기
    foreach (var line in lines)
    {
        AppendToScrollView(line);
    }
}

using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

public class LogReader
{
    // 생산자: 한 줄씩 비동기로 흘려보낸다
    public static async IAsyncEnumerable<string> ReadLinesAsync(string path)
    {
        using var reader = new StreamReader(path);
        string? line;
        while ((line = await reader.ReadLineAsync()) is not null)
        {
            yield return line; // 한 줄 도착 즉시 소비자에게 전달
        }
    }

    // 소비자: 한 줄 도착 즉시 화면에 추가
    public static async Task DisplayAsync(string path)
    {
        await foreach (var line in ReadLinesAsync(path))
        {
            System.Console.WriteLine(line);
        }
    }
}

// 생산자 메서드 자체는 사실상 wrapper다 — 진짜 코드는 상태머신에 있다
.method public hidebysig static class System.Collections.Generic.IAsyncEnumerable`1<string>
    ReadLinesAsync(string path) cil managed
{
    // 컴파일러가 만든 상태머신 인스턴스를 반환만 한다
    .custom instance void System.Runtime.CompilerServices.AsyncIteratorStateMachineAttribute::.ctor(...) = (...)
    newobj instance void '<ReadLinesAsync>d__0'::.ctor(int32) // ← 상태머신 생성
    ret
}

// 컴파일러가 자동 생성한 중첩 클래스 (이게 핵심)
.class nested private auto ansi sealed beforefieldinit '<ReadLinesAsync>d__0'
    extends System.Object
    implements
        IAsyncEnumerable`1<string>,
        IAsyncEnumerator`1<string>,    // ← 둘 다 구현
        IAsyncDisposable,
        IAsyncStateMachine
{
    .field public int32 '<>1__state'                        // 상태 머신의 현재 단계
    .field public AsyncIteratorMethodBuilder '<>t__builder' // 비동기 빌더 (Task용 빌더와 다른 전용 빌더)
    .field public ManualResetValueTaskSourceCore`1<bool>
        '<>v__promiseOfValueOrEnd'                          // ValueTask<bool>의 백킹
    .field private string '<>2__current'                    // Current 속성 값
    .field private bool '<>w__disposeMode'                  // DisposeAsync 호출됐는지 표시
    // ...
}

// 우리가 쓴 코드
await foreach (var line in ReadLinesAsync(path))
{
    Console.WriteLine(line);
}

// 컴파일러가 변환한 코드 (개념적으로 동등)
var enumerator = ReadLinesAsync(path).GetAsyncEnumerator(default);
try
{
    while (await enumerator.MoveNextAsync())
    {
        var line = enumerator.Current;
        Console.WriteLine(line);
    }
}
finally
{
    await enumerator.DisposeAsync();
}

// 소비자 측 C# 원본
public static async Task ConsumeAsync()
{
    await foreach (var n in GenerateAsync())
    {
        Console.WriteLine(n);
    }
}

// 컴파일러가 만든 ConsumeAsync의 상태머신 MoveNext (핵심만 발췌)
.class nested private auto ansi sealed beforefieldinit '<ConsumeAsync>d__1'
    extends System.ValueType
    implements IAsyncStateMachine
{
    .field public int32 '<>1__state'
    .field public AsyncTaskMethodBuilder '<>t__builder'
    .field private IAsyncEnumerator`1<int32> '<>7__wrap1'  // ← 열거자 보관
    // ...
}

// MoveNext 본문
IL_0012: call class IAsyncEnumerable`1<int32> BasicStream::GenerateAsync()
IL_0020: callvirt instance class IAsyncEnumerator`1<int32>
         IAsyncEnumerable`1<int32>::GetAsyncEnumerator(CancellationToken)  // ① 열거자 생성
IL_0044: callvirt instance int32 IAsyncEnumerator`1<int32>::get_Current()  // ② Current
IL_0049: call    void System.Console::WriteLine(int32)
IL_0054: callvirt instance ValueTask`1<bool>
         IAsyncEnumerator`1<int32>::MoveNextAsync()                        // ③ 다음 값 요청
IL_005c: call    instance ValueTaskAwaiter`1<bool> ValueTask`1<bool>::GetAwaiter()
IL_0064: call    instance bool ValueTaskAwaiter`1<bool>::get_IsCompleted() // 동기 완료 검사
IL_006b: ldarg.0
// ... await 지점에 멈췄다가 재개되면 ↓
IL_00aa: call    instance bool ValueTaskAwaiter`1<bool>::GetResult()
IL_00b1: brtrue.s IL_003e                                                  // true면 다시 Current로
// 루프 종료 후 finally 블록에서:
IL_00cf: callvirt instance ValueTask System.IAsyncDisposable::DisposeAsync() // ④ 비동기 정리

// 생산자 측 IL (핵심만)
.class nested private auto ansi sealed '<GenerateAsync>d__0'
    extends System.Object
    implements
        IAsyncEnumerable`1<int32>,
        IAsyncEnumerator`1<int32>,
        IAsyncDisposable,
        IAsyncStateMachine
{
    .field public AsyncIteratorMethodBuilder '<>t__builder'                      // ← 전용 빌더
    .field public ManualResetValueTaskSourceCore`1<bool> '<>v__promiseOfValueOrEnd' // ← ValueTask 백엔드
    .field private int32 '<>2__current'                                          // ← Current 값
    .field private bool '<>w__disposeMode'                                       // ← 정리 모드 플래그
}

// Before: 전부 List에 담아 반환 — 첫 화면이 늦고 GC 압박이 크다
public static async Task<List<int>> ReadAllAsync()
{
    var result = new List<int>();
    for (int i = 0; i < 1000; i++)
    {
        await Task.Yield();   // 비동기 작업 시뮬레이션
        result.Add(i);
    }
    return result;
}

// 호출자
List<int> all = await ReadAllAsync();   // 1000개 다 모일 때까지 기다림
foreach (var x in all) UseInUI(x);       // 그 다음에야 UI 갱신 시작

// Before의 IL (발췌)
IL_0001: newobj instance void List`1<int32>::.ctor()         // ← 힙에 List 1개 할당
.locals init ([0] valuetype '<ReadAllAsync>d__0', ...)
// 루프 1000회 동안 List에 Add
IL_004f: callvirt instance void List`1<int32>::Add(!0)
// 마지막에 List 통째로 SetResult
IL_0094: call instance void AsyncTaskMethodBuilder`1<List`1<int32>>::SetResult(!0)

using System.Runtime.CompilerServices;
using System.Threading;

// After: 한 건씩 흘려보낸다 — 첫 항목 즉시 사용 가능, GC 압박 적음
public static async IAsyncEnumerable<int> ReadStreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    for (int i = 0; i < 1000; i++)
    {
        ct.ThrowIfCancellationRequested();
        await Task.Yield();
        yield return i;
    }
}

// 호출자
await foreach (var x in ReadStreamAsync().WithCancellation(token))
{
    UseInUI(x);   // 첫 값 즉시 사용
}

// After의 IL (생산자 측 발췌)
.class nested '<ReadStreamAsync>d__0'
    implements IAsyncEnumerable`1<int32>, IAsyncEnumerator`1<int32>, IAsyncDisposable, IAsyncStateMachine
{
    .field public AsyncIteratorMethodBuilder '<>t__builder'
    .field public ManualResetValueTaskSourceCore`1<bool> '<>v__promiseOfValueOrEnd'  // ← ValueTask 재사용
    .field private int32 '<>2__current'
    .field public CancellationToken cancellationToken                                // ← 취소 토큰 보관
}

IL_0007: call valuetype AsyncIteratorMethodBuilder
         AsyncIteratorMethodBuilder::Create()                  // ← 일반 async와 다른 전용 빌더
IL_000c: stfld AsyncIteratorMethodBuilder ...::'<>t__builder'

// MoveNext 본문 — yield return마다 ValueTask 백엔드를 SetResult로 깨운다
IL_010e: ldflda ManualResetValueTaskSourceCore`1<bool> ...::'<>v__promiseOfValueOrEnd'
IL_0113: ldc.i4.1
IL_0115: call instance void ManualResetValueTaskSourceCore`1<bool>::SetResult(!0)  // 다음 값 도착 신호

using System.Collections.Generic;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Threading.Tasks;
using UnityEngine;

public class GalleryStreamer : MonoBehaviour
{
    // After: 한 장씩 비동기 스트리밍 (UniTask 또는 Awaitable 기반)
    public static async IAsyncEnumerable<Texture2D> StreamTexturesAsync(
        IReadOnlyList<string> paths,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        foreach (var path in paths)
        {
            ct.ThrowIfCancellationRequested();

            var request = Resources.LoadAsync<Texture2D>(path);
            while (!request.isDone)
            {
                await System.Threading.Tasks.Task.Yield(); // Unity의 메인 스레드 양보
            }

            if (request.asset is Texture2D tex)
            {
                yield return tex;
            }
        }
    }

    // 소비자: 갤러리 셀에 한 장 도착할 때마다 즉시 표시
    public async Task ShowGalleryAsync(IReadOnlyList<string> paths, CancellationToken ct)
    {
        int idx = 0;
        await foreach (var tex in StreamTexturesAsync(paths).WithCancellation(ct))
        {
            cells[idx++].SetTexture(tex); // 한 장 도착 즉시 화면 업데이트
        }
    }

    public Cell[] cells = default!;
    public class Cell : MonoBehaviour { public void SetTexture(Texture2D t) {} }
}

// 컴파일된 StreamTexturesAsync의 상태머신 (핵심)
.class nested '<StreamTexturesAsync>d__0'
    implements IAsyncEnumerable`1<Texture2D>, IAsyncEnumerator`1<Texture2D>, IAsyncDisposable
{
    .field public IReadOnlyList`1<string> paths
    .field public CancellationToken cancellationToken           // ← [EnumeratorCancellation]이 자동으로 채워줌
    .field private Texture2D '<>2__current'
    .field public AsyncIteratorMethodBuilder '<>t__builder'
}

// MoveNext에서 yield return 직전
IL_0093: ldarg.0
IL_0094: ldloc.s tex
IL_0096: stfld class Texture2D ...::'<>2__current'              // Current에 텍스처 1장 저장
IL_009b: ldarg.0
IL_009c: ldflda ManualResetValueTaskSourceCore`1<bool> ...::'<>v__promiseOfValueOrEnd'
IL_00a1: ldc.i4.1
IL_00a3: call instance void ManualResetValueTaskSourceCore`1<bool>::SetResult(!0)  // 소비자 깨우기
IL_00a8: ret                                                                       // MoveNext 종료

// ❌ 잘못된 패턴: IEnumerable<Task<T>> — 이름은 비슷하지만 전혀 다른 동작
public static IEnumerable<Task<int>> GenerateBad()
{
    for (int i = 0; i < 10; i++)
    {
        yield return SomeAsync(i); // foreach 직후 모든 Task가 즉시 시작됨
    }
}

// 호출자 — 10개 Task가 한꺼번에 fire되어 백엔드 폭격
foreach (var task in GenerateBad())
{
    var result = await task; // 이미 시작된 Task의 결과만 기다린다
}

// 잘못된 IEnumerable<Task<int>>의 IL — 일반 동기 반복기다
.method public hidebysig static class IEnumerable`1<Task`1<int32>>
    GenerateBad() cil managed
{
    newobj instance void '<GenerateBad>d__0'::.ctor(int32)  // ← 동기 반복기
    ret
}
// 상태머신은 IEnumerator`1<Task`1<int32>>만 구현 — IAsyncEnumerator 아님

// ✅ 올바른 패턴: IAsyncEnumerable<int> — 한 건씩 비동기로 순차 진행
public static async IAsyncEnumerable<int> GenerateGood()
{
    for (int i = 0; i < 10; i++)
    {
        var result = await SomeAsync(i); // 한 번에 하나씩 await
        yield return result;
    }
}

// 올바른 IAsyncEnumerable<int>의 IL
.method public hidebysig static class IAsyncEnumerable`1<int32>
    GenerateGood() cil managed
{
    newobj instance void '<GenerateGood>d__1'::.ctor(int32)
    ret
}
// 상태머신은 IAsyncEnumerable`1, IAsyncEnumerator`1, IAsyncDisposable, IAsyncStateMachine 모두 구현

// ❌ 잘못된 패턴: 그냥 CancellationToken을 받기만 함 — WithCancellation()이 무용지물
public static async IAsyncEnumerable<int> ProduceBad(CancellationToken ct)
{
    for (int i = 0; i < 100; i++)
    {
        ct.ThrowIfCancellationRequested();
        await Task.Delay(100);
        yield return i;
    }
}

// 호출자
var cts = new CancellationTokenSource(500);
await foreach (var x in ProduceBad(default).WithCancellation(cts.Token))  // ← 토큰이 ct로 전달되지 않음!
{
    Console.WriteLine(x); // 500ms 후에도 멈추지 않는다
}

// 잘못된 코드의 상태머신 (해당 메서드의 매개변수 보관 필드)
.field public CancellationToken ct
// → WithCancellation(token)으로 넘어온 토큰은 GetAsyncEnumerator(CancellationToken)으로
//   전달되지만, 컴파일러는 그것을 ct 필드에 자동으로 매핑할 줄 모른다.
//   ct에는 호출 시점의 default(빈 토큰)가 그대로 박혀 있다.

// ✅ 올바른 패턴: [EnumeratorCancellation]을 붙여 컴파일러가 토큰을 주입하게 함
public static async IAsyncEnumerable<int> ProduceGood(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    for (int i = 0; i < 100; i++)
    {
        ct.ThrowIfCancellationRequested();
        await Task.Delay(100, ct);
        yield return i;
    }
}

// 호출자
var cts = new CancellationTokenSource(500);
await foreach (var x in ProduceGood().WithCancellation(cts.Token))  // ← 토큰이 ct에 자동 주입됨
{
    Console.WriteLine(x); // 500ms 후 OperationCanceledException으로 정상 중단
}

// 올바른 코드의 매개변수 메타데이터
.param [1]
    .custom instance void EnumeratorCancellationAttribute::.ctor() = (...)  // ← 핵심 어트리뷰트
    .field public CancellationToken ct

// GetAsyncEnumerator(CancellationToken token) 안에서:
//   if (token.CanBeCanceled) {
//       this.ct = CancellationTokenSource.CreateLinkedTokenSource(callerToken, token).Token;
//   }
// → 컴파일러가 자동 생성한 코드가 호출자 토큰과 매개변수 토큰을 합쳐 ct에 주입

// 흔한 오해: "break하면 finally가 안 돌 거야"
await foreach (var line in ReadLinesAsync(path))
{
    if (line.StartsWith("STOP")) break; // ← 여기서 빠져나가면 파일이 안 닫히지 않을까?
    Process(line);
}

// 컴파일러가 자동으로 만든 finally 블록
.try
{
    // await foreach 본문
    leave.s IL_END
}
finally
{
    callvirt instance ValueTask IAsyncDisposable::DisposeAsync()  // ← 무조건 호출됨
    ...
    endfinally
}

// ❌ 잘못된 패턴: 라이브러리 코드인데 메인 스레드 컨텍스트로 자꾸 돌아옴
public async IAsyncEnumerable<int> LibraryStreamBad()
{
    for (int i = 0; i < 1000; i++)
    {
        await Task.Delay(10); // ConfigureAwait 없음 → 매번 동기화 컨텍스트 캡처/복귀 비용
        yield return i;
    }
}

// IL에서는 ConfigureAwait 호출이 보이지 않음 → 기본값(true)
IL_0019: call valuetype TaskAwaiter Task::GetAwaiter()
// 호출 컨텍스트(Unity 메인 스레드)가 캡처되어 매번 복귀

// ✅ 올바른 패턴: 라이브러리에서는 ConfigureAwait(false)
public async IAsyncEnumerable<int> LibraryStreamGood()
{
    for (int i = 0; i < 1000; i++)
    {
        await Task.Delay(10).ConfigureAwait(false); // 컨텍스트 복귀 비용 제거
        yield return i;
    }
}

// 소비자 측에서도 한 번에 적용 가능
await foreach (var x in LibraryStreamGood().ConfigureAwait(false))
{
    // ...
}

// ConfigureAwait(false) 적용 시
IL_0019: call valuetype ConfiguredTaskAwaitable ...::ConfigureAwait(bool)
IL_001e: call valuetype ConfiguredTaskAwaiter ConfiguredTaskAwaitable::GetAwaiter()
// SynchronizationContext를 캡처하지 않음 → 스레드 풀에서 그대로 재개

// Before: C# 7.x — 콜백 체인 또는 Channel<T>로 수동 구현
public static void Subscribe(Action<int> onNext, Action onComplete)
{
    Task.Run(async () =>
    {
        for (int i = 0; i < 10; i++)
        {
            await Task.Delay(100);
            onNext(i);
        }
        onComplete();
    });
}

// After: C# 8 — 언어 차원 지원
public static async IAsyncEnumerable<int> ProduceAsync()
{
    for (int i = 0; i < 10; i++)
    {
        await Task.Delay(100);
        yield return i;
    }
}

await foreach (var x in ProduceAsync())
{
    Console.WriteLine(x);
}

// C# 8 이후 IL에 새로 추가된 형
class System.Collections.Generic.IAsyncEnumerable`1<T>
class System.Collections.Generic.IAsyncEnumerator`1<T>
class System.IAsyncDisposable
class System.Runtime.CompilerServices.AsyncIteratorStateMachineAttribute
class System.Runtime.CompilerServices.AsyncIteratorMethodBuilder
class System.Runtime.CompilerServices.EnumeratorCancellationAttribute

// C# 9: 확장 메서드로 await foreach 가능
public struct MyStream { /* IAsyncEnumerable 미구현 */ }

public static class MyStreamExtensions
{
    public static IAsyncEnumerator<int> GetAsyncEnumerator(this MyStream s,
        CancellationToken ct = default) => new MyEnumerator();
}

// 호출자 — 확장 메서드만으로 동작
await foreach (var x in new MyStream())  // ← 인터페이스 구현 없이도 OK
{
    // ...
}

// .NET 6 이상: 동시성 제한과 함께 병렬 처리
await Parallel.ForEachAsync(
    ProduceAsync(),                                           // IAsyncEnumerable<T>
    new ParallelOptions { MaxDegreeOfParallelism = 4 },
    async (item, ct) =>
    {
        await ProcessAsync(item, ct);
    });

// .NET 9: 여러 Task를 먼저 끝나는 순서대로 await foreach
Task<int>[] tasks = { Task1(), Task2(), Task3() };
await foreach (Task<int> completed in Task.WhenEach(tasks))
{
    var result = await completed; // 먼저 끝난 작업의 결과를 즉시 처리
    Process(result);
}

목차

1. 한 줄 정의
2. 시작하기 전에 알아야 할 핵심
3. 왜 이 주제가 까다로운가 — "예외가 사라졌어요"
4. 핵심 메커니즘 — Task에 예외가 저장되고 await에서 부활한다
5. 내부 동작 — ExceptionDispatchInfo가 스택 트레이스를 보존하는 방법
6. Task.WhenAll의 첫 예외 함정
7. async void와 미관찰 예외 — 사라지는 예외의 정체
8. 실전 적용 — Unity 모바일에서의 패턴
9. 함정과 주의사항
10. C# 버전별 변화
11. 정리 — 이것만 기억하세요

// Unity에서 흔히 마주치는 상황
public async void OnButtonClicked()
{
    LoadDataAsync(); // ⚠️ await 빼먹음
}

private async Task LoadDataAsync()
{
    await Task.Delay(100);
    throw new InvalidOperationException("데이터 없음");
}

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        try
        {
            await LoadAsync();
        }
        catch (InvalidOperationException ex)
        {
            // ✅ 여기서 잡힙니다
            Console.WriteLine($"잡았다: {ex.Message}");
        }
    }

    static async Task LoadAsync()
    {
        await Task.Delay(50);
        throw new InvalidOperationException("로드 실패");
    }
}

.method private hidebysig instance void MoveNext () cil managed
{
    .locals init (
        [0] int32 V_0,
        [1] class [System.Runtime]System.Exception V_1
    )

    .try
    {
        // 사용자 코드 본문 (await 분기·throw 포함)
        IL_0040: newobj  instance void [System.Runtime]System.InvalidOperationException::.ctor(string)
        IL_0045: throw    // ← 사용자가 던진 예외
    }
    catch [System.Runtime]System.Exception
    {
        IL_0050: stloc.1
        IL_0051: ldarg.0
        IL_0052: ldflda  '<>t__builder'
        // 예외를 Task로 흘려보낸다 — 호출 스택으로 던지지 않는다
        IL_0057: call instance void
                 [System.Runtime]System.Runtime.CompilerServices.AsyncTaskMethodBuilder::SetException(class System.Exception)
        IL_005c: leave.s IL_0070
    }
    IL_0070: ret
}

static async Task ValidateThenWorkAsync(string? input)
{
    if (input is null)
        throw new ArgumentNullException(nameof(input)); // ❗ 즉시 throw가 아님
    await Task.Delay(50);
}

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        try
        {
            await Outer();
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.ToString());
        }
    }

    static async Task Outer()
    {
        await Task.Delay(10);
        await Inner();
    }

    static async Task Inner()
    {
        await Task.Delay(10);
        throw new InvalidOperationException("진짜 발생 지점");
    }
}

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var t1 = FailAsync(50, "A 실패");
        var t2 = FailAsync(60, "B 실패");
        var t3 = FailAsync(70, "C 실패");

        try
        {
            await Task.WhenAll(t1, t2, t3);
        }
        catch (Exception ex)
        {
            // ⚠️ 첫 번째 예외 하나만 잡힙니다
            Console.WriteLine($"잡힌 예외: {ex.GetType().Name} — {ex.Message}");
        }
    }

    static async Task FailAsync(int delay, string msg)
    {
        await Task.Delay(delay);
        throw new InvalidOperationException(msg);
    }
}

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var t1 = FailAsync(50, "A 실패");
        var t2 = FailAsync(60, "B 실패");
        var t3 = FailAsync(70, "C 실패");
        var all = Task.WhenAll(t1, t2, t3);

        try
        {
            await all;
        }
        catch
        {
            // ✅ 모든 예외를 보고 싶으면 합쳐진 Task의 Exception을 직접 꺼낸다
            if (all.Exception is AggregateException ae)
            {
                foreach (var inner in ae.Flatten().InnerExceptions)
                {
                    Console.WriteLine($"- {inner.Message}");
                }
            }
        }
    }

    static async Task FailAsync(int delay, string msg)
    {
        await Task.Delay(delay);
        throw new InvalidOperationException(msg);
    }
}

// await all; 컴파일 결과 (요약)
IL_0080: ldloca.s   awaiter
IL_0082: call instance !0 valuetype
            [System.Runtime]System.Runtime.CompilerServices.TaskAwaiter::GetResult()
// ↑ Task.Exception이 AggregateException이라도
//   여기서 InnerExceptions[0]만 ExceptionDispatchInfo로 꺼내 throw

var winner = await Task.WhenAny(t1, t2);
await winner; // 예외 처리는 여기서

using UnityEngine;
using UnityEngine.UI;
using System;
using System.Threading.Tasks;

public class ShopController : MonoBehaviour
{
    [SerializeField] private Button buyButton;

    void Start() => buyButton.onClick.AddListener(OnBuyClicked);

    // ❌ Bad — async void에서 예외가 새면 앱이 죽는다
    private async void OnBuyClicked()
    {
        await PurchaseAsync(); // 네트워크 실패 시 throw
    }

    // ✅ Good — 이벤트 핸들러 자체는 async void라도, 안에서 try-catch로 감싼다
    private async void OnBuyClickedSafe()
    {
        try
        {
            await PurchaseAsync();
        }
        catch (Exception ex)
        {
            ShowErrorPopup(ex.Message);
            Debug.LogException(ex);
        }
    }

    private async Task PurchaseAsync()
    {
        await Task.Delay(100);
        throw new InvalidOperationException("결제 서버 응답 없음");
    }

    private void ShowErrorPopup(string msg) { /* ... */ }
}

// 프로그램 진입점에서 한 번만 등록
TaskScheduler.UnobservedTaskException += (sender, e) =>
{
    Debug.LogError($"[Unobserved] {e.Exception}");
    e.SetObserved(); // 관찰됐다고 표시 — 더 이상 위로 전파하지 않음
};

// fire-and-forget 패턴 (보통은 피해야 함)
_ = LongRunningAsync(); // ← await 없이 그냥 시작

// ❌ Bad — async 본문에 검증
public async Task SaveAsync(string? path)
{
    if (path is null)
        throw new ArgumentNullException(nameof(path)); // Task로 감싸짐
    await File.WriteAllTextAsync(path, "data");
}

// 호출자
_ = controller.SaveAsync(null); // 검증 예외가 묵살됨

// ✅ Good — 검증은 동기 래퍼, 비동기 본체는 분리
public Task SaveAsync(string? path)
{
    if (path is null)
        throw new ArgumentNullException(nameof(path)); // 즉시 throw
    return SaveCoreAsync(path);
}

private async Task SaveCoreAsync(string path)
{
    await File.WriteAllTextAsync(path, "data");
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

public sealed class AssetBootstrap
{
    private readonly List<string> _bundleKeys = new() { "ui", "stage1", "stage2", "audio" };

    public async Task<BootResult> LoadAllAsync()
    {
        var tasks = _bundleKeys
            .Select(key => (Key: key, Task: LoadBundleAsync(key)))
            .ToList();

        // 모두 끝날 때까지 기다리되, 예외는 따로 모은다
        try
        {
            await Task.WhenAll(tasks.Select(x => x.Task));
        }
        catch
        {
            // await는 첫 예외만 던지므로, 여기서 catch만 하고 실제 분류는 아래에서
        }

        var failures = tasks
            .Where(x => x.Task.IsFaulted)
            .Select(x => (x.Key, Error: x.Task.Exception!.GetBaseException()))
            .ToList();

        return new BootResult(
            Successful: tasks.Where(x => !x.Task.IsFaulted).Select(x => x.Key).ToList(),
            Failed: failures);
    }

    private async Task LoadBundleAsync(string key)
    {
        await Task.Delay(50);
        if (key == "stage2")
            throw new InvalidOperationException("stage2 번들 손상");
    }
}

public record BootResult(
    List<string> Successful,
    List<(string Key, Exception Error)> Failed);

// 게임 라이브러리 내부 코드
public async Task<byte[]> DownloadAsync(string url)
{
    using var http = new HttpClient();
    // ✅ 라이브러리 코드는 컨텍스트 복귀가 불필요
    var bytes = await http.GetByteArrayAsync(url).ConfigureAwait(false);
    return bytes;
}

try
{
    await DownloadAsync(url, token);
}
catch (OperationCanceledException) when (token.IsCancellationRequested)
{
    // 정상적인 취소 — 사용자에게 에러 토스트를 띄우지 않는다
    Debug.Log("사용자가 다운로드를 취소했습니다.");
}
catch (Exception ex)
{
    // 진짜 오류
    ShowErrorPopup(ex);
    Debug.LogException(ex);
}

public ValueTask<int> GetCachedOrLoadAsync(string key)
{
    if (_cache.TryGetValue(key, out var cached))
        return new ValueTask<int>(cached); // 즉시 반환 — 할당 없음
    return new ValueTask<int>(LoadAsync(key));
}

// ❌ Bad — await는 AggregateException을 풀어서 던진다
try
{
    await Task.WhenAll(t1, t2, t3);
}
catch (AggregateException ae) // 절대 잡히지 않음
{
    foreach (var inner in ae.InnerExceptions) Log(inner);
}

// ✅ Good — 예외 타입 자체로 잡고, 모든 예외를 보려면 Task.Exception 사용
try
{
    var all = Task.WhenAll(t1, t2, t3);
    await all;
}
catch (Exception)
{
    if (all.Exception is AggregateException ae)
        foreach (var inner in ae.Flatten().InnerExceptions) Log(inner);
}

// ❌ Bad — 예외가 미관찰로 묻힘
_ = SaveLogAsync(payload);

// ✅ Good — 예외 처리를 명시한 fire-and-forget 헬퍼
public static class TaskExt
{
    public static void Forget(this Task task, string context)
    {
        task.ContinueWith(t =>
            {
                if (t.IsFaulted)
                    Debug.LogError($"[{context}] {t.Exception?.Flatten()}");
            },
            TaskContinuationOptions.OnlyOnFaulted);
    }
}

// 호출
SaveLogAsync(payload).Forget(nameof(SaveLogAsync));

// ❌ Bad — try가 너무 일찍 끝난다
public async Task LoadAsync()
{
    Task download;
    try
    {
        download = StartDownloadAsync(); // 시작만 함
    }
    catch (Exception ex)
    {
        Log(ex);
        return;
    }
    await download; // ← 진짜 예외는 여기서 발생
}

// ✅ Good — await를 try 안에 둔다
public async Task LoadAsync()
{
    try
    {
        var download = StartDownloadAsync();
        await download;
    }
    catch (Exception ex)
    {
        Log(ex);
    }
}

// ❌ Bad — Wait/Result는 AggregateException을 그대로 던진다
try
{
    var result = LoadAsync().Result; // ← 데드락 위험 + AggregateException
}
catch (InvalidOperationException) // 잡히지 않음
{
    // ...
}

// ✅ Good — 항상 await 사용
try
{
    var result = await LoadAsync();
}
catch (InvalidOperationException)
{
    // 잡힌다
}

// Task → UniTask 변환
UniTask uni = someTask.AsUniTask(); // 예외도 함께 전달됨
await uni; // Task의 예외 그대로 throw

// ❌ C# 5에서는 컴파일 에러
try
{
    await DownloadAsync();
}
catch (Exception ex)
{
    // C# 6부터 OK
    await LogToServerAsync(ex);
    throw;
}
finally
{
    // C# 6부터 OK
    await CleanupTempFilesAsync();
}

// 취소 예외만 분리해 잡되, 토큰이 실제로 발사된 경우만
catch (OperationCanceledException) when (token.IsCancellationRequested)
{
    // 정상 종료
}

목차

1. 한 줄 정의
2. 시작하기 전에 알아야 할 핵심
3. 왜 협조적 취소인가 — `Thread.Abort`가 폐기된 이유
4. 두 객체의 역할 — 발신기와 수신기
5. ADEPT — 토큰을 직접 만지며 이해하기
6. IsCancellationRequested vs ThrowIfCancellationRequested
7. IL 관점 — `ThrowIfCancellationRequested`는 얼마나 가벼운가
8. CancelAfter — 타임아웃의 표준 패턴
9. OperationCanceledException 처리 — 오류가 아닙니다
10. 토큰 전파 — 끝까지 넘기지 않으면 의미가 없다
11. Register 콜백 — 토큰을 모르는 코드에 끼우기
12. Unity 실전 활용
13. 일반적인 함정 정리
14. 빠른 점검 체크리스트
15. 한 걸음 더
16. 마무리

using var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;     // 작업에 전달할 수신기

var task = DoWorkAsync(token);            // 작업 시작

await Task.Delay(1000);
cts.Cancel();                             // 외부에서 취소 신호

try { await task; }
catch (OperationCanceledException) { Console.WriteLine("취소됨"); }

using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var cts = new CancellationTokenSource();
        cts.CancelAfter(TimeSpan.FromSeconds(2));   // 2초 후 자동 취소

        try
        {
            await CountAsync(cts.Token);
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("취소됨 (정상)");
        }
    }

    static async Task CountAsync(CancellationToken token)
    {
        for (int i = 0; i < 100; i++)
        {
            token.ThrowIfCancellationRequested();   // 취소 시 OperationCanceledException
            Console.WriteLine($"카운트 {i}");
            await Task.Delay(500, token);            // Delay도 토큰을 받음
        }
    }
}

async Task ProcessAsync(CancellationToken token)
{
    while (HasMore())
    {
        if (token.IsCancellationRequested)
        {
            CleanupBuffers();    // 정리
            return;              // 자연 종료 → TaskStatus.RanToCompletion
        }
        await DoStepAsync();
    }
}

async Task ProcessAsync(CancellationToken token)
{
    while (HasMore())
    {
        token.ThrowIfCancellationRequested();   // → TaskStatus.Canceled
        await DoStepAsync();
    }
}

async Task ProcessAsync(CancellationToken token)
{
    try
    {
        while (HasMore())
        {
            if (token.IsCancellationRequested)
            {
                await FlushPartialAsync();   // 부분 결과 저장 등 정리
                token.ThrowIfCancellationRequested();   // 상태 명확히
            }
            await DoStepAsync();
        }
    }
    finally { Cleanup(); }
}

using System.Threading;

public class Worker
{
    public void Check(CancellationToken token)
    {
        token.ThrowIfCancellationRequested();
    }

    public bool Poll(CancellationToken token)
    {
        return token.IsCancellationRequested;
    }
}

.method public hidebysig instance void Check(valuetype CancellationToken token) cil managed
{
    ldarga.s  token
    call      instance void [System.Threading]CancellationToken::ThrowIfCancellationRequested()
    ret
}

// 실제 .NET 런타임 구현 요지
public void ThrowIfCancellationRequested()
{
    if (IsCancellationRequested)
        ThrowOperationCanceledException();   // 분리된 cold path
}

public bool IsCancellationRequested
{
    get
    {
        CancellationTokenSource source = _source;
        return source != null && source.IsCancellationRequested;
    }
}

[MemoryDiagnoser]
public class CancellationBenchmark
{
    private CancellationToken _token = new CancellationTokenSource().Token;

    [Benchmark] public bool Poll() => _token.IsCancellationRequested;
    [Benchmark] public void Throw() => _token.ThrowIfCancellationRequested();
}

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
// 또는: cts.CancelAfter(5000);

try
{
    var data = await httpClient.GetStringAsync(url, cts.Token);
}
catch (OperationCanceledException) when (cts.IsCancellationRequested)
{
    Console.WriteLine("5초 타임아웃");
}

public async Task<string> FetchAsync(string url, CancellationToken caller)
{
    using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
        caller, timeoutCts.Token);

    try
    {
        return await _http.GetStringAsync(url, linkedCts.Token);
    }
    catch (OperationCanceledException) when (timeoutCts.IsCancellationRequested
                                             && !caller.IsCancellationRequested)
    {
        throw new TimeoutException("5초 타임아웃");
    }
}

// 잘못된 예
public async Task<string> FetchAsync(string url, CancellationToken caller)
{
    var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(5));   // using 없음
    var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(caller, timeoutCts.Token);
    return await _http.GetStringAsync(url, linkedCts.Token);
    // timeoutCts·linkedCts가 GC될 때까지 타이머·콜백이 살아있음
}

try
{
    await ProcessAsync(token);
}
catch (Exception ex)
{
    _logger.LogError(ex, "처리 실패");   // 취소도 "실패"로 기록됨
    ShowErrorDialog(ex.Message);          // 사용자에게 "오류 발생!"
}

try
{
    await ProcessAsync(token);
}
catch (OperationCanceledException) when (token.IsCancellationRequested)
{
    // 정상 취소 — 로그 안 남김 또는 Info 레벨로만
    _logger.LogInformation("사용자 요청으로 작업 취소");
}
catch (Exception ex)
{
    _logger.LogError(ex, "처리 실패");
    ShowErrorDialog(ex.Message);
}

try
{
    Task.WaitAll(t1, t2, t3);
}
catch (AggregateException agg)
{
    foreach (var inner in agg.InnerExceptions)
    {
        if (inner is OperationCanceledException) continue;   // 취소는 무시
        _logger.LogError(inner, "병렬 작업 실패");
    }
}

public async Task SaveUserAsync(User user, CancellationToken token)
{
    await _db.SaveAsync(user);                    // ❌ 토큰 누락
    await _http.PostAsync(url, content);          // ❌ 토큰 누락
    token.ThrowIfCancellationRequested();          // 너무 늦음 — 이미 다 했음
}

public async Task SaveUserAsync(User user, CancellationToken token)
{
    await _db.SaveAsync(user, token);
    await _http.PostAsync(url, content, token);
}

public Task<int> ComputeAsync(int[] data, CancellationToken token)
{
    return Task.Run(() =>
    {
        int sum = 0;
        foreach (var x in data)
        {
            token.ThrowIfCancellationRequested();   // 람다 안에서 사용
            sum += Compute(x);
        }
        return sum;
    }, token);   // ← Task.Run 자체에도 전달
}

public async Task LoadConfigAsync()
{
    // 설정 로드는 취소되어선 안 됨 — 명시적으로 None 전달
    await _config.LoadAsync(CancellationToken.None);
}

public async Task<byte[]> ReadLegacyAsync(Stream stream, CancellationToken token)
{
    // 이 Read는 토큰을 받지 않음 — Register로 우회
    using CancellationTokenRegistration reg = token.Register(() => stream.Close());

    try
    {
        var buf = new byte[4096];
        int read = await stream.ReadAsync(buf, 0, buf.Length);   // 토큰 없이 호출
        return buf.AsSpan(0, read).ToArray();
    }
    catch (ObjectDisposedException) when (token.IsCancellationRequested)
    {
        throw new OperationCanceledException(token);
    }
    // using으로 reg 자동 Dispose
}

using UnityEngine;
using System.Threading.Tasks;

public class EnemySpawner : MonoBehaviour
{
    async void Start()
    {
        try
        {
            await SpawnLoopAsync(destroyCancellationToken);
        }
        catch (System.OperationCanceledException) { /* GameObject 파괴됨 */ }
    }

    async Task SpawnLoopAsync(System.Threading.CancellationToken token)
    {
        while (!token.IsCancellationRequested)
        {
            Spawn();
            await Task.Delay(2000, token);
        }
    }
}

using Cysharp.Threading.Tasks;
using System.Threading;

public class Loader : MonoBehaviour
{
    public async UniTaskVoid LoadAsync()
    {
        var token = this.GetCancellationTokenOnDestroy();   // UniTask 확장
        var prefab = await Resources.LoadAsync<GameObject>("Boss")
                                    .ToUniTask(cancellationToken: token);
        Instantiate(prefab);
    }
}

public class GameLifetime : MonoBehaviour
{
    public static CancellationTokenSource ApplicationExitCts { get; } = new();

    void OnApplicationQuit() => ApplicationExitCts.Cancel();
}

public async Task DoAsync(CancellationToken token)   // 시그니처에는 있음
{
    await SomethingAsync();   // ❌ 토큰을 안 넘김
}

public void Subscribe(CancellationToken token, Action callback)
{
    token.Register(callback);   // ❌ Dispose하지 않음
}

lock (_lock)
{
    _cts.Cancel();   // ❌ Register 콜백이 같은 스레드에서 실행될 수 있음
                     //    콜백 내부에서 _lock을 잡으려 하면 데드락
}

try { await DoAsync(token); }
catch { }   // ❌ 취소 정보가 위로 전파되지 않음

class Service
{
    private CancellationToken _token;   // ❌ 한 번 취소되면 영구히 취소 상태
    public void Init(CancellationToken token) => _token = token;
}

목차

1. 문제 제기 — `await` 한 번에 하나씩만 기다리면 생기는 일
2. 개념 정의 — 두 가지 조합기(Combinator)
3. 내부 동작 — 게이트키퍼 Task와 카운트다운
4. 실전 적용 — 언제 어떻게 쓰는가
5. 함정과 주의사항
6. C# 버전별 변화
7. 정리

async Task LoadGameAsync()
{
    var character = await LoadCharacterAsync();   // 300ms 대기
    var level     = await LoadLevelAsync();       // 250ms 대기
    var player    = await FetchPlayerDataAsync(); // 400ms 대기
    // 총 950ms
}

using System.Threading.Tasks;

async Task<int[]> WhenAllExampleAsync()
{
    Task<int> a = Task.FromResult(10);
    Task<int> b = Task.FromResult(20);
    Task<int> c = Task.FromResult(30);

    int[] results = await Task.WhenAll(a, b, c);
    // results = [10, 20, 30]  — 입력 순서 그대로
    return results;
}

async Task<int> WhenAnyExampleAsync()
{
    Task<int> fast = Task.Delay(50).ContinueWith(_ => 1);
    Task<int> slow = Task.Delay(500).ContinueWith(_ => 2);

    Task<int> first = await Task.WhenAny(fast, slow); // Task<Task<int>> 를 await하면 Task<int>
    // first 는 fast 와 같은 객체
    return await first; // 1
}

private static async Task<int[]> ParallelAsync(List<Task<int>> tasks)
{
    return await Task.WhenAll(tasks);
}

// ParallelAsync 의 컴파일된 메서드 본체
.method private hidebysig static
    class [System.Runtime]System.Threading.Tasks.Task`1<int32[]>
    ParallelAsync(class [...]List`1<class [...]Task`1<int32>> tasks) cil managed
{
    // 1. 상태 머신 구조체를 스택에 만들고
    .locals init ([0] valuetype Program/'<ParallelAsync>d__1' V_0)

    ldloca.s   V_0
    call       valuetype [...]AsyncTaskMethodBuilder`1<int32[]>::Create()
    stfld      ...t__builder            // 빌더 초기화
    ldloca.s   V_0
    ldarg.0
    stfld      ...tasks                 // 파라미터 저장
    ldloca.s   V_0
    ldc.i4.m1
    stfld      ...<>1__state            // state = -1 (시작 전)

    // 2. 상태 머신 시작
    ldloca.s   V_0
    ldflda     ...t__builder
    ldloca.s   V_0
    call       AsyncTaskMethodBuilder`1::Start<...>(!!0&)
    ldloca.s   V_0
    ldflda     ...t__builder
    call       AsyncTaskMethodBuilder`1::get_Task()
    ret
}

// 상태 머신 내부 MoveNext 의 핵심 (Task.WhenAll 호출과 await 처리)
IL_00ae: call class [...]Task`1<int32[]> System.Threading.Tasks.Task::WhenAll(...)
IL_00b3: callvirt instance valuetype TaskAwaiter`1<int32[]> Task`1::GetAwaiter()
IL_00b8: stloc.3
IL_00bb: call instance bool TaskAwaiter`1::get_IsCompleted()
IL_00c0: brtrue.s IL_0101                // 이미 완료면 동기 경로
// ↓ 미완료면 콜백 등록 + leave (호출자에게 제어권 반환)
IL_00d8: ldloca.s 3
IL_00db: call instance void AsyncTaskMethodBuilder::AwaitUnsafeOnCompleted<...>(...)
IL_00e0: leave IL_018d
// ↓ 재진입 시 결과 추출
IL_0103: call instance !0 TaskAwaiter`1::GetResult()

async Task DemoOrderAsync()
{
    var slow = Task.Run(async () => { await Task.Delay(300); return "slow"; });
    var fast = Task.Run(async () => { await Task.Delay(50);  return "fast"; });

    string[] results = await Task.WhenAll(slow, fast);
    // results[0] == "slow"  ← 입력 순서대로
    // results[1] == "fast"
}

async Task<int[]> SequentialAsync(List<Task<int>> tasks)
{
    var results = new int[tasks.Count];
    for (int i = 0; i < tasks.Count; i++)
    {
        results[i] = await tasks[i]; // ← 한 개씩만 기다림
    }
    return results;
}

async Task<int[]> ParallelAsync(List<Task<int>> tasks)
{
    return await Task.WhenAll(tasks); // ← 동시에 기다림
}

// SequentialAsync 의 MoveNext 일부 — 루프 안의 await
IL_004x: ldarg.0
IL_004y: ldloc.x                         // tasks[i]
IL_004z: callvirt Task`1::GetAwaiter()
IL_005x: stloc.x
IL_005y: call    TaskAwaiter`1::get_IsCompleted()
IL_005z: brtrue.s ...                    // 동기 경로
IL_006x: call    AwaitUnsafeOnCompleted  // ← 루프마다 콜백 등록
IL_006y: leave   ...                     // ← 매 반복마다 호출자에게 양보
// 다음 반복에서 GetResult 후 results[i] = ...

// ParallelAsync 의 MoveNext 일부
IL_00ae: call    Task::WhenAll(...)      // 게이트키퍼 Task 생성 (즉시 반환)
IL_00b3: callvirt Task`1::GetAwaiter()
IL_00bb: call    TaskAwaiter`1::get_IsCompleted()
IL_00c0: brtrue.s IL_0101
IL_00db: call    AwaitUnsafeOnCompleted // ← 콜백 등록은 단 한 번
IL_00e0: leave   IL_018d
IL_0103: call    TaskAwaiter`1::GetResult()

async Task<string> FetchWithTimeoutAsync(int timeoutMs)
{
    Task<string> work  = FetchFromServerAsync();
    Task         delay = Task.Delay(timeoutMs);

    Task first = await Task.WhenAny(work, delay);

    if (first == delay)
        throw new TimeoutException($"{timeoutMs}ms 초과");

    return await work; // 서버 응답 결과
}

private static async Task<int> WithTimeoutAsync(Task<int> work, int timeoutMs)
{
    Task delay = Task.Delay(timeoutMs);
    if (await Task.WhenAny(work, delay) == delay)
        throw new TimeoutException();
    return await work;
}

// MoveNext 핵심 부분 — WhenAny 호출과 참조 비교
ldarg.0
ldfld    ...work
ldarg.0
ldfld    ...delay
call     class Task Task::WhenAny(class Task, class Task)  // ← 두 인자 버전
callvirt TaskAwaiter`1::GetAwaiter()
// ... await 상태 머신 (생략) ...
call     TaskAwaiter`1::GetResult()                        // ← 완료된 Task 반환
ldarg.0
ldfld    ...delay
ceq                                                         // ← 참조 비교 (==)
brfalse.s ... (work 결과 반환 경로)
newobj   instance void TimeoutException::.ctor()
throw

using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class SceneLoader : MonoBehaviour
{
    public async Task EnterStageAsync(string stageId)
    {
        // 1. 모든 비동기 작업을 동시에 시작 (await 하지 않음)
        Task<GameObject>      characterTask = LoadAssetAsync<GameObject>("character");
        Task<GameObject>      stageTask     = LoadAssetAsync<GameObject>($"stage_{stageId}");
        Task<AudioClip>       bgmTask       = LoadAssetAsync<AudioClip>($"bgm_{stageId}");
        Task<PlayerSaveData>  saveTask      = ServerApi.FetchSaveAsync();

        // 2. 한 번에 기다림 — 가장 오래 걸리는 작업의 시간만큼만 걸림
        await Task.WhenAll(characterTask, stageTask, bgmTask, saveTask);

        // 3. 결과 사용 (이미 완료됐으므로 .Result 안전)
        Instantiate(characterTask.Result);
        Instantiate(stageTask.Result);
        AudioSource.PlayClipAtPoint(bgmTask.Result, Vector3.zero);
        ApplySaveData(saveTask.Result);
    }

    static Task<T> LoadAssetAsync<T>(string key) where T : Object
    {
        var op = Addressables.LoadAssetAsync<T>(key);
        return op.Task; // Addressables는 Task로 변환 가능
    }
}

async Task<string> PickFastestServerAsync(string[] candidates)
{
    using var cts = new CancellationTokenSource();
    var pingTasks = new Task<string>[candidates.Length];

    for (int i = 0; i < candidates.Length; i++)
    {
        pingTasks[i] = PingAsync(candidates[i], cts.Token);
    }

    Task<string> winner = await Task.WhenAny(pingTasks);

    cts.Cancel(); // 나머지 서버 ping은 취소 (네트워크 낭비 방지)

    return await winner;
}

try
{
    await Task.WhenAll(taskA, taskB, taskC);
}
catch (Exception ex)
{
    // ex 는 첫 번째 예외 하나뿐!
    // 나머지 두 개는 어디로?
    Debug.LogError(ex);
}

Task all = Task.WhenAll(taskA, taskB, taskC);
try
{
    await all;
}
catch
{
    // all.Exception 에는 모든 예외가 AggregateException 으로 담겨 있다
    foreach (var inner in all.Exception!.InnerExceptions)
    {
        Debug.LogError(inner);
    }
}

// catch 블록 내부에서 변수에 저장된 Task에 접근
ldloc.0                           // Task all
callvirt Task::get_Exception()    // AggregateException? 반환
callvirt AggregateException::get_InnerExceptions()
// foreach 루프

Task<string> work = FetchAsync();
Task         delay = Task.Delay(2000);

await Task.WhenAny(work, delay);
// "타임아웃이니까 work는 자동으로 멈췄겠지?" — 아니다!
// work 는 계속 진행 중이며, 끝나면 결과를 버려도 그 사이 자원·돈을 쓴다

async Task<string> FetchWithTimeoutAsync(int timeoutMs)
{
    using var cts = new CancellationTokenSource(timeoutMs);
    try
    {
        // 서버 호출이 cts.Token 을 협조적으로 확인하도록 만든다
        return await FetchAsync(cts.Token);
    }
    catch (OperationCanceledException)
    {
        throw new TimeoutException($"{timeoutMs}ms 초과");
    }
}

// Unity UI 이벤트 핸들러
public void OnButtonClick()
{
    var task = LoadAssetAsync();
    task.Wait(); // ← UI 스레드 블로킹! 게임 화면 멈춤
    // Unity SynchronizationContext에서는 데드락도 가능
}

public async void OnButtonClick()
{
    var task = LoadAssetAsync();
    await task; // ← 메인 스레드 양보, 끝나면 다시 돌아옴
}

async Task ProcessInOrderAsync(List<Task<int>> tasks)
{
    while (tasks.Count > 0)
    {
        // N번 호출 × 매번 N개 Task에 콜백 등록 = O(N²)
        Task<int> done = await Task.WhenAny(tasks);
        tasks.Remove(done);
        Process(await done);
    }
}

async Task ProcessInOrderAsync(IEnumerable<Task<int>> tasks)
{
    await foreach (Task<int> completed in Task.WhenEach(tasks))
    {
        Process(await completed);
    }
}

void Update()
{
    // 매 프레임 WhenAll 호출 — GC 스파이크의 원인
    _ = Task.WhenAll(SomeWorkAsync(), AnotherWorkAsync());
}

// 핫패스에서는 동기 처리
void Update() { DoSyncWork(); }

// 비동기가 꼭 필요하면 한 번만 시작하고 상태 추적
Task? _pending;
void Update()
{
    if (_pending == null || _pending.IsCompleted)
    {
        _pending = Task.WhenAll(SomeWorkAsync(), AnotherWorkAsync());
    }
}

// Before — .NET 5 이전 (또는 Unity 2022 LTS, .NET Standard 2.1)
async Task<string> FetchWithTimeoutAsync(int timeoutMs)
{
    Task<string> work  = FetchAsync();
    Task         delay = Task.Delay(timeoutMs);

    if (await Task.WhenAny(work, delay) == delay)
        throw new TimeoutException();
    return await work;
}

// After — .NET 6+
async Task<string> FetchWithTimeoutAsync(int timeoutMs)
{
    return await FetchAsync().WaitAsync(TimeSpan.FromMilliseconds(timeoutMs));
}

// Before — WhenAny 패턴
call class Task Task::Delay(int32)              // delay Task 할당
call class Task Task::WhenAny(class Task, class Task)  // 게이트키퍼 Task 할당
ceq                                              // 참조 비교
// ... 분기 ...

// After — WaitAsync
call class Task`1<...> Task`1::WaitAsync(valuetype TimeSpan)
// 끝

// Before — WhenAny 루프 (O(N²))
async Task ProcessAsync(List<Task<int>> tasks)
{
    while (tasks.Count > 0)
    {
        var done = await Task.WhenAny(tasks);
        tasks.Remove(done);
        Console.WriteLine(await done);
    }
}

// After — WhenEach (O(N), 비동기 스트림)
async Task ProcessAsync(IEnumerable<Task<int>> tasks)
{
    await foreach (Task<int> completed in Task.WhenEach(tasks))
    {
        Console.WriteLine(await completed);
    }
}

목차

1. 문제 제기 — "버튼을 누르면 게임이 통째로 죽는다"
2. 개념 정의 — 세 반환형의 의미
3. 내부 동작 — 컴파일러가 만드는 세 가지 빌더
4. 실전 적용 — 반환형 선택 규칙
5. 함정과 주의사항
6. C# 버전별 변화
7. 정리

public class DataLoader : MonoBehaviour
{
    public async void LoadProfileAsync()  // 무심코 void 선택
    {
        var profile = await FetchFromServer();
        if (profile == null)
            throw new InvalidOperationException("프로필이 없습니다");
        ApplyProfile(profile);
    }
}

// 호출부 — 버튼 클릭 핸들러
public void OnButtonClick()
{
    try
    {
        loader.LoadProfileAsync();  // 예외가 뜨면 잡힐까?
    }
    catch (Exception e)
    {
        Debug.LogError(e.Message);  // 절대 실행되지 않습니다
    }
}

public async Task LoadProfileAsync()  // void → Task
{
    var profile = await FetchFromServer();
    if (profile == null)
        throw new InvalidOperationException("프로필이 없습니다");
    ApplyProfile(profile);
}

// 호출부
public async void OnButtonClick()  // 이벤트 핸들러는 어쩔 수 없이 void
{
    try
    {
        await loader.LoadProfileAsync();  // await 가 예외를 다시 던져준다
    }
    catch (Exception e)
    {
        Debug.LogError(e.Message);  // 정상적으로 잡힌다
    }
}

public class AsyncReturnTypes
{
    // (1) 결과가 있는 비동기 — Task<T>
    public async Task<int> GetUserScoreAsync(int userId)
    {
        await Task.Delay(100);   // 비동기 작업 (네트워크 호출 가정)
        return 9999;             // T(int) 결과 반환
    }

    // (2) 결과가 없는 비동기 — Task
    public async Task SaveUserScoreAsync(int userId, int score)
    {
        await Task.Delay(100);   // 비동기 작업
        // return 문 없음
    }

    // (3) 이벤트 핸들러용 — async void
    public async void OnSaveButtonClicked(object sender, EventArgs e)
    {
        try
        {
            await SaveUserScoreAsync(1, 9999);
        }
        catch (Exception ex)
        {
            // 이벤트 핸들러 안에서는 반드시 try-catch
            Debug.LogError(ex);
        }
    }
}

public async Task<int> GetValueAsync()
{
    await Task.Delay(10);
    return 42;
}

// 상태 머신 구조체 필드 정의
.field public valuetype System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1<int32>
    '<>t__builder'

// MoveNext() 정상 종료 — 결과를 Task<int> 에 저장
IL_008a: call instance void
    AsyncTaskMethodBuilder`1<int32>::SetResult(!0)   // 42를 Task에 박음

// MoveNext() catch 블록 — 예외를 Task<int> 에 저장
IL_0075: call instance void
    AsyncTaskMethodBuilder`1<int32>::SetException(class System.Exception)

public async Task DoWorkAsync()
{
    await Task.Delay(10);
}

// 상태 머신 구조체 필드 정의
.field public valuetype System.Runtime.CompilerServices.AsyncTaskMethodBuilder
    '<>t__builder'

// MoveNext() 정상 종료 — 결과 없이 Task 만 완료
IL_008a: call instance void
    AsyncTaskMethodBuilder::SetResult()              // 인자 없음

// MoveNext() catch 블록 — 예외를 Task 에 저장
IL_0075: call instance void
    AsyncTaskMethodBuilder::SetException(class System.Exception)

public async void FireAndForgetAsync()
{
    await Task.Delay(10);
    throw new InvalidOperationException("async void에서 발생한 예외");
}

// 상태 머신 구조체 필드 정의 — 빌더 타입만 다르다
.field public valuetype System.Runtime.CompilerServices.AsyncVoidMethodBuilder
    '<>t__builder'

// MoveNext() catch 블록 — Task 가 없으므로 SynchronizationContext 로 직송
IL_007e: call instance void
    AsyncVoidMethodBuilder::SetException(class System.Exception)
//  ↑ 동일한 메서드 이름이지만, 내부 구현이 완전히 다르다.
//  AsyncTaskMethodBuilder.SetException → Task.Exception 에 저장
//  AsyncVoidMethodBuilder.SetException → SynchronizationContext.Post(throw)

public class SaveSystem : MonoBehaviour
{
    // 잘못된 패턴 — 라이브러리성 메서드를 async void 로 노출
    public async void SaveGameAsync(GameData data)
    {
        var json = JsonUtility.ToJson(data);
        await File.WriteAllTextAsync(savePath, json);
        // 실패 시 예외가 어디로 가는지 호출자가 알 수 없음
    }
}

// 호출부
public class GameManager : MonoBehaviour
{
    private SaveSystem saveSystem;

    public async Task OnLevelClearAsync()
    {
        try
        {
            saveSystem.SaveGameAsync(currentData);   // 즉시 반환 (Task 가 없어 await 불가)
            await ShowVictoryAnimationAsync();        // 저장 완료 전에 진행
            // 저장이 끝났는지 호출자가 확인할 방법이 없다
        }
        catch (IOException e)
        {
            Debug.LogError("저장 실패");  // 잡히지 않는다
        }
    }
}

public class SaveSystem : MonoBehaviour
{
    // 올바른 패턴 — 호출자에게 Task 를 돌려준다
    public async Task SaveGameAsync(GameData data)
    {
        var json = JsonUtility.ToJson(data);
        await File.WriteAllTextAsync(savePath, json);
    }
}

public class GameManager : MonoBehaviour
{
    public async Task OnLevelClearAsync()
    {
        try
        {
            await saveSystem.SaveGameAsync(currentData);  // 완료까지 대기
            await ShowVictoryAnimationAsync();             // 저장 후 애니메이션
        }
        catch (IOException e)
        {
            Debug.LogError($"저장 실패: {e.Message}");    // 정상적으로 잡힌다
            ShowSaveFailedDialog();
        }
    }
}

// ❌ 결과를 멤버 변수로 흘려보내는 패턴 (async void 강요)
public class ScoreLoader : MonoBehaviour
{
    public int LoadedScore;  // 외부 상태에 의존

    public async void LoadScoreAsync(int userId)
    {
        LoadedScore = await FetchFromServer(userId);
        // 호출자는 LoadedScore 가 갱신됐는지 어떻게 알지?
    }
}

// 호출부 — 폴링 + 타임아웃 같은 임시방편 코드 양산
while (scoreLoader.LoadedScore == 0) await Task.Yield();

// ✅ Task<T> 로 결과를 직접 돌려준다
public class ScoreLoader : MonoBehaviour
{
    public async Task<int> LoadScoreAsync(int userId)
    {
        return await FetchFromServer(userId);  // 결과를 Task<int> 에 담아 반환
    }
}

// 호출부 — 한 줄
int score = await scoreLoader.LoadScoreAsync(userId);

// ❌ async void
.field public valuetype AsyncVoidMethodBuilder '<>t__builder'

// ✅ async Task
.field public valuetype AsyncTaskMethodBuilder '<>t__builder'

// ❌ 절대 금지 — 라이브러리(공용 모듈) 메서드는 async void 금지
public class NetworkClient
{
    public async void SendRequestAsync(string url)  // 사용자가 await 못 함
    {
        var response = await httpClient.GetAsync(url);
        ProcessResponse(response);
    }
}

// ✅ 라이브러리 메서드는 항상 Task / Task<T>
public class NetworkClient
{
    public async Task<HttpResponseMessage> SendRequestAsync(string url)
    {
        var response = await httpClient.GetAsync(url);
        return response;
    }
}

// ❌ 위험 — 예외가 새어 나가면 앱이 죽는다
public class UIController : MonoBehaviour
{
    public async void OnLoadButtonClicked()
    {
        var data = await LoadAsync();  // 예외 발생 가능
        UpdateUI(data);
    }
}

// ✅ 이벤트 핸들러는 메서드 전체를 try-catch 로 감싼다
public class UIController : MonoBehaviour
{
    public async void OnLoadButtonClicked()
    {
        try
        {
            var data = await LoadAsync();
            UpdateUI(data);
        }
        catch (Exception e)
        {
            Debug.LogException(e);
            ShowErrorDialog(e.Message);
        }
    }
}

// ❌ async void 메서드는 테스트가 거짓 통과한다
[Test]
public void SaveTest_async_void()
{
    var system = new SaveSystem();
    system.SaveGameAsync_void(testData);   // async void
    // 테스트 러너는 이 줄을 지나면 즉시 다음으로 진행
    // SaveGameAsync 가 끝나기 전에 테스트가 "성공" 으로 종료
    Assert.IsTrue(File.Exists(savePath));  // 파일이 아직 없을 수 있음
}

// ✅ async Task 면 테스트 러너가 완료까지 대기한다
[Test]
public async Task SaveTest_async_Task()
{
    var system = new SaveSystem();
    await system.SaveGameAsync(testData);  // 완료까지 대기
    Assert.IsTrue(File.Exists(savePath));   // 파일이 반드시 존재
}

// ⚠️ 주의 — Start() 같은 단발성 라이프사이클 메서드만 허용. Update() 는 금지
public class BadUsage : MonoBehaviour
{
    private async void Update()  // ❌ 매 프레임 호출 + 비동기 = 폭주
    {
        await LoadDataAsync();   // 60 FPS 면 초당 60번 새로운 비동기 작업 시작
        UpdateUI();
    }

    private async void Start()   // ✅ 한 번만 호출되므로 OK (이벤트 핸들러 성격)
    {
        try
        {
            await InitializeAsync();
        }
        catch (Exception e)
        {
            Debug.LogException(e);
        }
    }
}

// ❌ GameObject 가 파괴된 뒤에 await 가 끝나면 MissingReferenceException
public async Task LoadAndApplyAsync()
{
    var data = await FetchAsync();         // 5초 걸림
    // 그동안 사용자가 씬을 바꿔서 이 GameObject 가 파괴됨
    transform.position = data.spawnPoint;  // 💥 MissingReferenceException
}

// ✅ destroyCancellationToken (Unity 2022.2+) 으로 안전하게 취소
public async Task LoadAndApplyAsync()
{
    var data = await FetchAsync(destroyCancellationToken);
    transform.position = data.spawnPoint;  // 파괴되면 여기 도달하지 않음
}

// C# 7.0+ — 결과가 동기적으로 즉시 준비되는 경우 GC 할당 회피
public async ValueTask<int> GetCachedScoreAsync(int userId)
{
    if (cache.TryGetValue(userId, out var score))
        return score;  // Task 객체 할당 없이 즉시 반환

    return await FetchFromServer(userId);
}

// AsyncMethodBuilderAttribute 로 사용자 정의 빌더 지정 가능
[AsyncMethodBuilder(typeof(MyTaskMethodBuilder))]
public struct MyTask { /* ... */ }

// ✅ Unity 모바일 게임에서 사실상의 표준
public class GameLoader : MonoBehaviour
{
    public async UniTask<UserData> LoadUserAsync()  // Task<T> 대신
    {
        var data = await UnityWebRequest.Get(url).SendWebRequest();
        return Parse(data);
    }

    // async UniTaskVoid: async void 의 안전한 대체재
    public async UniTaskVoid OnButtonClicked()
    {
        try
        {
            var user = await LoadUserAsync();
            ApplyUI(user);
        }
        catch (Exception e)
        {
            Debug.LogException(e);
        }
    }
}

목차

1. [문제 제기] — 비동기 작업이 늘어나면 코드가 콜백 미로가 된다
2. [개념 정의] — async 는 "이 메서드 안에서 await 를 쓰겠다"는 표시, await 는 "제어권 양보 + 콜백 등록"
3. [내부 동작] — 반환형 5종과 그들이 awaitable 인 이유
4. [실전 적용] — I/O 는 await, CPU 는 await Task.Run, DoAsync 가 보이면 동기 버전 금지
5. [함정과 주의사항] — .Result/.Wait, fire-and-forget, async void 남용
6. [C# 버전별 변화] — 시작은 5.0, 점차 확장
7. [정리] — 핵심 체크리스트

// async/await 없이 콜백으로 비동기 흐름을 잇는 옛날 패턴
public void LoadUserFlow(int userId, Action<UserProfile> onDone)
{
    api.GetUser(userId, user =>
    {
        api.GetInventory(user.Id, inventory =>
        {
            api.DownloadIcon(inventory.IconUrl, icon =>
            {
                cache.Save(icon, () =>
                {
                    onDone(new UserProfile(user, inventory, icon));
                });
            });
        });
    });
}

using System.Net.Http;
using System.Threading.Tasks;

public class HtmlFetcher
{
    private static readonly HttpClient client = new();

    // async 한정자, Task<string> 반환형, 메서드 이름 끝에 Async
    public async Task<string> GetAsync(string url)
    {
        // await 는 Task<string> 앞에만 사용 가능
        var html = await client.GetStringAsync(url);
        return html.Trim();
    }
}

// 호출자 진입점 — 우리가 작성한 GetAsync() 의 실제 IL
.method public hidebysig instance class Task`1<string> GetAsync(string url) cil managed
{
    .custom instance void AsyncStateMachineAttribute::.ctor(class Type) // 컴파일러가 붙인 어트리뷰트
    .locals init ([0] valuetype Sample1/'<GetAsync>d__1') // 상태 머신 구조체

    IL_0000: ldloca.s 0
    IL_0002: call AsyncTaskMethodBuilder`1<string>::Create() // 빌더 생성
    IL_0007: stfld ...t__builder
    IL_000c: ldloca.s 0
    IL_000e: ldarg.1
    IL_000f: stfld string ...url   // 인자를 상태 머신 필드에 저장
    IL_0014: ldloca.s 0
    IL_0016: ldc.i4.m1
    IL_0017: stfld int32 ...'<>1__state' // 초기 상태 -1
    IL_001c: ldloca.s 0
    IL_001e: ldflda ...t__builder
    IL_0023: ldloca.s 0
    IL_0025: call AsyncTaskMethodBuilder`1::Start<...>(!!0&) // 상태 머신 가동
    IL_002a: ldloca.s 0
    IL_002c: ldflda ...t__builder
    IL_0031: call get_Task() // 빌더에서 Task 꺼내서 호출자에게 반환
    IL_0036: ret
}

// 우리가 적은 한 줄(`var html = await client.GetStringAsync(url);`)이
// 컴파일러가 만든 MoveNext 안에서 어떻게 펼쳐졌는지 핵심 부분만
IL_000a: ldsfld HttpClient Sample1::client
IL_0010: ldfld string ...url
IL_0015: callvirt Task`1<string> HttpClient::GetStringAsync(string)
IL_001a: callvirt TaskAwaiter`1::GetAwaiter()
IL_001f: stloc.2
IL_0022: call TaskAwaiter`1::get_IsCompleted() // 이미 끝났으면 그대로 진행
IL_0027: brtrue.s IL_0065
// 끝나지 않았으면: 상태 머신을 힙으로 박싱, 콜백 등록, 메서드 빠져나감
IL_0042: call AsyncTaskMethodBuilder`1::AwaitUnsafeOnCompleted<...>(...)
IL_0047: leave.s IL_009f
// ↓ 작업 완료 시 시스템이 다시 들어와 IL_0049 부터 실행
IL_0065: ldloca.s 2
IL_0067: call TaskAwaiter`1::GetResult() // string 결과 꺼냄
IL_006c: callvirt String::Trim() // 우리가 적은 .Trim() 호출

using System.IO;
using System.Threading.Tasks;

public class ReturnTypeShowcase
{
    // 1. Task : 결과값이 없는 작업
    public async Task SaveAsync(string path, string text)
    {
        await File.WriteAllTextAsync(path, text);
        // return 키워드 자체를 안 쓰는 게 자연스럽다
    }

    // 2. Task<T> : 결과값이 있는 작업 — 가장 흔한 형태
    public async Task<int> CountLinesAsync(string path)
    {
        var lines = await File.ReadAllLinesAsync(path);
        return lines.Length; // int 를 return 하면 컴파일러가 Task<int> 로 감싸 준다
    }

    // 3. ValueTask<T> : 동기 완료 가능성이 매우 높을 때 (캐시 적중 등)
    private string? cached;
    public ValueTask<string> ReadCachedAsync(string path)
    {
        if (cached is not null)
            return new ValueTask<string>(cached); // 동기 완료, 힙 할당 0
        return new ValueTask<string>(LoadAsync(path));
    }
    private async Task<string> LoadAsync(string path)
    {
        var text = await File.ReadAllTextAsync(path);
        cached = text;
        return text;
    }

    // 4. async void : 이벤트 핸들러에서만 — 일반 메서드에서는 절대 금지
    // private async void OnButtonClick(object sender, EventArgs e) { ... }
}

public class VoidDanger
{
    // 절대 따라하면 안 되는 패턴
    public async void DoBadlyAsync()
    {
        await Task.Delay(10);
        throw new InvalidOperationException("터졌어요"); // 어디서도 잡을 수 없음
    }

    public async Task CallerAsync()
    {
        try
        {
            DoBadlyAsync(); // Task 가 없어 await 불가
            // 메서드가 끝났는지 알 길도 없음
        }
        catch (InvalidOperationException) // 여기로 안 들어옴
        {
            // 도달 불가
        }
    }
}

// ❌ Before — 동기 호출로 스레드를 통째로 점유
public string Fetch(string url)
{
    var client = new HttpClient();
    string html = client.GetStringAsync(url).Result; // 응답 올 때까지 스레드 블로킹
    return html.Trim();
}

// ✅ After — await 로 외부에 위임, 스레드 자유
public async Task<string> FetchAsync(string url)
{
    var client = new HttpClient();
    string html = await client.GetStringAsync(url); // 응답 동안 스레드 점유 없음
    return html.Trim();
}

// Before: GetSync 의 핵심 IL — 동기 .Result 호출
.method public hidebysig instance Task`1<string> GetSync(string url) cil managed
{
    IL_0000: ldsfld HttpClient Sample2::client
    IL_0005: ldarg.1
    IL_0006: callvirt Task`1<string> HttpClient::GetStringAsync(string)
    IL_000b: callvirt !0 Task`1<string>::get_Result() // ← 여기서 스레드 블로킹
    IL_0010: callvirt string String::Trim()
    IL_0015: call Task`1<!!0> Task::FromResult<string>(!!0)
    IL_001a: ret
}

public class HeavyCompute
{
    // ❌ Before — 메인 스레드에서 직접 계산. UI 가 멈춘다.
    public int RunSync()
    {
        return Compute(); // CPU 100% 사용, 그동안 화면·이벤트 처리 정지
    }

    // ✅ After — Task.Run 으로 스레드 풀에 위임 후 await
    public async Task<int> RunAsync()
    {
        int result = await Task.Run(() => Compute());
        return result;
    }

    private int Compute()
    {
        int sum = 0;
        for (int i = 0; i < 100; i++) sum += i;
        return sum;
    }
}

// After: RunAsync 의 핵심 IL — Task.Run 도 결국 awaitable Task 를 반환
IL_0011: ldloc.1
IL_0012: ldftn instance int32 Sample3::'<RunAsync>b__0_0'() // 람다 본문
IL_0018: newobj Func`1<int32>::.ctor(...)
IL_001d: call Task`1<!!0> Task::Run<int32>(class Func`1<!!0>) // 스레드 풀에 작업 던지기
IL_0022: callvirt TaskAwaiter`1<int32> Task`1<int32>::GetAwaiter()
IL_002a: call TaskAwaiter`1<int32>::get_IsCompleted()
IL_002f: brtrue.s IL_006d
// 완료 안 됐으면 콜백 등록 후 메서드 종료 (메인 스레드는 자유)
IL_004a: call AsyncTaskMethodBuilder`1<int32>::AwaitUnsafeOnCompleted<...>(...)
IL_006f: call TaskAwaiter`1<int32>::GetResult()

// File.ReadAllText vs File.ReadAllTextAsync
// HttpClient.Send vs HttpClient.SendAsync
// SqlCommand.ExecuteReader vs SqlCommand.ExecuteReaderAsync
// Stream.Read vs Stream.ReadAsync

// ❌ async 메서드 안에서 동기 API 호출 — async 의 의미가 사라짐
public async Task<string> LoadConfigBadAsync()
{
    string text = File.ReadAllText("config.json"); // 스레드 블로킹
    return text;
}

// ✅ 같은 메서드의 비동기 버전을 await
public async Task<string> LoadConfigGoodAsync()
{
    string text = await File.ReadAllTextAsync("config.json");
    return text;
}

// ❌ async 코드와 동기 코드를 .Result 로 억지로 붙이는 패턴
public string LoadSync()
{
    return LoadAsync().Result; // UI 스레드/ASP.NET 컨텍스트에서 deadlock 가능
}

private async Task<string> LoadAsync()
{
    var html = await client.GetStringAsync("https://...");
    return html.Trim(); // ← 이 줄은 원래 호출 스레드(UI)로 돌아가고 싶어함
}

// ✅ async 를 끝까지 전파(async all the way)
public async Task<string> LoadAsync2()
{
    return await LoadAsync();
}

// ❌ Task 를 그냥 버린다 — 컴파일러 경고 CS4014 가 뜨지만 무시되곤 함
public async Task SaveUserAsync(User user)
{
    db.WriteAsync(user); // await 누락
    log.WriteAsync($"Saved {user.Id}"); // await 누락
    // 메서드는 두 작업이 끝나기도 전에 반환됨
}

// ✅ 반드시 await
public async Task SaveUserAsync2(User user)
{
    await db.WriteAsync(user);
    await log.WriteAsync($"Saved {user.Id}");
}

// ✅ 정말 fire-and-forget 이 의도라면 명시적으로 _ 에 대입하고 예외 처리 책임을 진다
public void FireAndForget(User user)
{
    _ = Task.Run(async () =>
    {
        try { await audit.WriteAsync(user); }
        catch (Exception ex) { logger.LogError(ex, "audit 실패"); }
    });
}

public class BadHandler
{
    // 이벤트 시그니처상 async void — 여기까지는 OK
    private async void OnButtonClick(object sender, EventArgs e)
    {
        await DoSomethingAsync();
    }

    // ❌ 이 메서드를 다른 곳에서 호출 — 추적 불가, 예외 손실
    public void RetryAll()
    {
        OnButtonClick(this, EventArgs.Empty);
        OnButtonClick(this, EventArgs.Empty);
        // 두 번 모두 끝났는지 알 수 없고, 실패해도 못 잡음
    }
}

public class GoodHandler
{
    // 실제 로직은 Task 반환 메서드로 분리
    public async Task DoSomethingAsync() { /* ... */ }

    // 이벤트 핸들러는 진짜 한 줄짜리 어댑터
    private async void OnButtonClick(object sender, EventArgs e)
    {
        try { await DoSomethingAsync(); }
        catch (Exception ex) { ShowError(ex); }
    }

    public async Task RetryAllAsync()
    {
        await DoSomethingAsync();
        await DoSomethingAsync();
    }
}

public class BadCoroutineLikeAsync : MonoBehaviour
{
    // ❌ Task.Run 안에서 UnityEngine API 호출
    public async Task LoadAsync()
    {
        await Task.Run(() =>
        {
            transform.position = Vector3.zero; // 메인 스레드 외 호출 → 예외
        });
    }

    // ❌ Update 마다 async 메서드를 호출하며 await 누락 — 매 프레임 fire-and-forget
    private void Update()
    {
        FetchOptionalAsync(); // Task 누수 + 예외 손실
    }
    private async Task FetchOptionalAsync() { await Task.Yield(); }
}

public class GoodAsyncInUnity : MonoBehaviour
{
    // ✅ Task.Run 에는 순수 C# 계산만, UnityEngine API 는 메인 스레드 복귀 후
    public async Task LoadAsync()
    {
        byte[] data = await DownloadAsync();
        var parsed = await Task.Run(() => HeavyParse(data)); // 순수 C# 계산
        // 여기는 다시 메인 스레드 (Task.Run 이 완료된 뒤 await 가 복귀시킴)
        transform.position = parsed.Spawn;
    }

    private Task<byte[]> DownloadAsync() => Task.FromResult(new byte[] { });
    private SpawnInfo HeavyParse(byte[] _) => new() { Spawn = Vector3.zero };
    private struct SpawnInfo { public Vector3 Spawn; }
}

// C# 5.0 (.NET 4.5) — 첫 등장 시 가능한 모양
public async Task<int> CountAsync_v5(string path)
{
    using var reader = new StreamReader(path);
    int count = 0;
    while (await reader.ReadLineAsync() != null) count++;
    return count;
}

// C# 7.0 + : ValueTask<T> 로 동기 완료 경로 최적화
public ValueTask<int> CountCachedAsync(string key)
{
    if (cache.TryGetValue(key, out int v))
        return new ValueTask<int>(v); // 힙 할당 0
    return new ValueTask<int>(LoadAndCacheAsync(key));
}

// C# 7.1 + : async Main
public static async Task<int> Main(string[] args)
{
    await SomeStartupAsync();
    return 0;
}

// C# 8.0 + : 비동기 스트림
public async IAsyncEnumerable<string> StreamLinesAsync(string path)
{
    using var reader = new StreamReader(path);
    string? line;
    while ((line = await reader.ReadLineAsync()) is not null)
        yield return line;
}