[Rust 공식문서 한국어 정리] ㊲. Rust Pin과 Unpin 가이드

[Rust 공식문서 한국어 정리] ㊲. Rust Pin과 Unpin 가이드

원문 제목: std::pin — Rust Standard Library Documentation
작성자: Rust Standard Library Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 1. 서론 — 이 문서가 다루는 내용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

이 문서는 Rust의 Pin과 Unpin 개념을 사용해 메모리에서 이동 불가능한 타입을 만드는 방법을 설명합니다.
비동기 프로그래밍에서 Future가 낮� 티 참조를 포함할 때, 힙상의 고정된 주소를 보장하는 메커니즘을 다룹니다.
Pin<&mut T>, Pin>, Unpin 트레이트의 관계와, 안전하게 Pin을 다루는 패턴을 중심으로 설명합니다.
Self-referential 구조체를 안전하게 구현하는 방법과, 이와 관련된 메모리 안전성 보장을 핵심 주제로 삼습니다.
async/await 낮� 티 동작을 이해하거나, 저수준 Future를 직접 구현하려는 개발자에게 필수적인 내용입니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔑 2. 핵심 개념 4가지
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

① Pin

: 포인터 P가 가리키는 값이 메모리에서 이동되지 않음을 보장하는 래퍼 타입입니다.
② Unpin: 메모리 이동이 안전한 타입에 자동으로 구현되는 마커 트레이트입니다.
③ !Unpin: 이동이 안전하지 않은 타입으로, Pin<&mut T>로 고정된 상태에서만 접근해야 합니다.
④ Self-Referential: 구조체 낮� 의 어떤 필드가 다른 필드를 참조하는 구조로, 이동 시 invalidate될 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 3. 주요 내용 상세
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Pin은 포인터를 래핑하여 가리키는 값이 메모리 상에서 이동되지 않도록 보장합니다.
Pin<&mut T>는 T가 !Unpin인 경우, 해당 참조를 통해 안전하게 낮� 티 데이터를 조작할 수 있게 합니다.
Pin::new는 Unpin 타입에 대해서만 생성할 수 있으며, Pin::new_unchecked는 unsafe로 !Unpin 타입에도 적용됩니다.

Unpin은 대부분의 타입에 자동으로 구현되는 auto trait입니다.
원시 포인터, PhantomPinned 등을 포함하는 타입은 !Unpin이 되어 이동 불가능함을 표현합니다.
async fn이나 async 블록에서 생성된 익명 Future도 낮� 티에 self-referential 데이터를 포함할 수 있어 !Unpin입니다.

Self-referential 구조체는 Rust에서 안전하게 구현하기 어려운 패턴입니다.
구조체가 이동되면 낮� 티 참조가 dangling이 되므로, Pin으로 고정하여 이동을 금지해야 합니다.
PhantomPinned를 필드로 추가하면 해당 구조체는 !Unpin이 되어, Pin 없이는 안전하게 이동할 수 없습니다.

Pin의 메서드는 고정된 데이터를 안전하게 조작할 수 있도록 설계되었습니다.
Pin::set은 낮� 티 값을 새 값으로 교체하되, 메모리 주소는 유지합니다.
Pin::map_unchecked와 Pin::get_unchecked_mut은 낮� 티 필드에 접근할 때 사용하며, unsafe가 필요할 수 있습니다.

비동기 런타임에서 Pin은 핵심적인 역할을 합니다.
Future::poll은 Pin<&mut Self>를 받으며, 이는 Future 상태가 이동되지 않음을 보장합니다.
이를 통해 async/await 구문이 낮� 티적으로 생성하는 self-referential 상태를 안전하게 관리할 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠 4. 실전 활용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

커스텀 Future를 구현할 때 poll 메서드의 Pin<&mut Self>를 올바르게 다룹니다.
Self-referential 구조체를 만들 때 PhantomPinned를 포함시키고 Pin>로 힙에 고정합니다.
Pin::map_unchecked로 낮� 티 필드에 접근하며, 메모리 이동 가능성을 원천 차단합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 5. 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Pin과 Unpin은 self-referential 타입을 안전하게 다루기 위한 Rust의 핵심 메커니즘입니다.
async/await의 안전성이 Pin에 기반하고 있으며, 이를 이해해야 비동기 코드의 낮� 티를 제대로 파악할 수 있습니다.
메모리 고정이 필요한 저수준 코드에서만 !Unpin을 사용하고, 일반 타입은 Pin 없이도 안전하게 이동 가능합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 출처 링크
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

원문: https://doc.rust-lang.org/std/pin/index.html
Rust Asynchronous Book Pin: https://rust-lang.github.io/async-book/04_pinning/01_chapter.html

#Rust #Pin #Unpin #Async #Future #SelfReferential #MemorySafety #번역