규칙 세 줄 ★

① 모든 값에는 주인(owner)이 있다.
② 주인은 한 번에 한 명이다.
③ 주인이 스코프를 벗어나면 값은 해제된다.

{
    let s = String::from("안녕");   // ① s 가 주인
    // s 를 쓴다
}                                   // ③ 스코프 끝 → 힙 메모리 해제 (drop 호출)

let a = String::from("안녕");
let b = a;                          // ② 주인이 b 로 이동 (a 는 무효)

// 그래서 다음이 전부 자동으로 보장됩니다
//   · 해제를 빠뜨릴 수 없다      (주인이 사라지면 반드시 해제)
//   · 두 번 해제할 수 없다        (주인은 한 명)
//   · 해제 후 접근할 수 없다      (무효가 된 이름은 컴파일 에러)
//
// ★ C++ 의 RAII 와 같은 아이디어인데, C++ 는 '지키면 좋은 관례'이고
//   Rust 는 '어기면 컴파일이 안 되는 규칙'입니다. 이 차이가 전부입니다.

언제 해제되는지 눈으로 보기

struct Res(&'static str);
impl Drop for Res {
    fn drop(&mut self) { println!("[{}] 해제", self.0); }
}

fn take(r: Res) { println!("[{}] 받음", r.0); }   // r 이 주인이 됨

fn main() {
    let a = Res("A");
    let b = Res("B");
    take(b);                     // ★ 여기서 B 가 해제됩니다 (함수 끝에서)
    println!("함수 뒤");
}                                // A 해제

// 출력
//   [B] 받음
//   [B] 해제        ← take 가 끝나는 시점
//   함수 뒤
//   [A] 해제

// ★ "값을 함수에 넘기면 그 함수가 주인이 되고, 함수가 끝나면 해제된다"
//   이 감각이 잡히면 소유권 에러의 90%가 이해됩니다.

데이터가 흐르는 방향을 먼저 정합니다

// ★ 설계 질문 하나: "이 데이터의 주인은 누구인가?"
//   이 질문에 답하면 시그니처가 저절로 정해집니다.

// 파이프라인 — 소유권이 한 방향으로 흐릅니다 (가장 다루기 쉬움)
fn read(path: &Path) -> io::Result<Vec<u8>>;      // 만들어서 준다
fn decode(raw: Vec<u8>) -> Result<Image>;         // 받아서 변환
fn resize(img: Image, w: u32) -> Image;           // 받아서 돌려줌
fn save(img: &Image, path: &Path) -> io::Result<()>;  // 빌려서 씀

let out = save(&resize(decode(read(p)?)?, 800), q)?;

// 저장소 — 하나가 소유하고 나머지는 빌립니다
struct App { users: Vec<User> }              // App 이 주인
impl App {
    fn find(&self, id: u64) -> Option<&User> { }     // 빌려 줌
    fn add(&mut self, u: User) { self.users.push(u) } // 받아서 보관
}

// ★ 이 두 형태로 대부분이 해결됩니다.
//   Rc<RefCell<T>> 가 필요해졌다면 대개 설계를 한 번 더 볼 신호입니다 (o10).

C++ · 파이썬 개발자가 자주 하는 실수

// ❌ ① 자기 참조 구조체 — 만들 수 없습니다
// struct Bad { data: String, view: &str }    // view 가 data 를 가리킴
// ✅ 인덱스나 범위로 표현하세요
struct Ok { data: String, view: std::ops::Range<usize> }
impl Ok { fn view(&self) -> &str { &self.data[self.view.clone()] } }

// ❌ ② 양방향 링크 (부모 ↔ 자식)
// struct Node { parent: &Node, children: Vec<Node> }
// ✅ 인덱스 기반 아레나 — 트리·그래프의 정석입니다 ★
struct Tree { nodes: Vec<Node> }
struct Node { parent: Option<usize>, children: Vec<usize> }
// (slotmap · petgraph 크레이트가 이걸 잘 만들어 둔 것입니다)

// ❌ ③ 전역 가변 상태
// static mut CACHE: HashMap<..> = ..;        // unsafe · 2024 에디션 금지
// ✅
use std::sync::{OnceLock, Mutex};
static CACHE: OnceLock<Mutex<HashMap<String, u64>>> = OnceLock::new();

// ❌ ④ 클래스 상속을 흉내 내기
// ✅ 합성 + 트레이트 (o05)

비용은 0 입니다 — 검사가 컴파일 타임이니까

// 소유권·빌림 검사는 전부 컴파일 타임에 끝납니다.
// 생성된 기계어에는 '검사 코드'가 한 줄도 없습니다. ★

fn sum(v: &[i32]) -> i32 { v.iter().sum() }
// → C 로 손으로 쓴 for 루프와 동일한 어셈블리가 나옵니다 (⚡ e03)

// 남는 것은 딱 하나: drop 호출
//   컴파일러가 각 스코프 끝에 drop 호출을 '끼워 넣습니다'.
//   조건부로 이동됐을 수 있으면 'drop flag' (스택의 bool)를 씁니다.

let s = String::new();
if cond { consume(s); }
// → 컴파일러가 숨은 bool 하나를 두고, 스코프 끝에서
//   "아직 내 것이면 drop" 을 판단합니다.
//   이 플래그는 보통 최적화로 사라집니다.

// 확인 방법
//   cargo asm / godbolt.org 에서 -O 어셈블리 비교 (⚡ e03)

Drop 을 구현하면 잃는 것들

struct Guard { data: Vec<u8> }
impl Drop for Guard { fn drop(&mut self) { } }

// ★ Drop 을 구현하면 '부분 이동'이 금지됩니다
// fn take(g: Guard) -> Vec<u8> { g.data }
//   error[E0509]: cannot move out of type `Guard`,
//                 which implements the `Drop` trait
//   (필드를 빼가면 drop 이 무엇을 정리해야 할지 모호해지기 때문)

// 해법 — Option 으로 감싸고 take
struct Guard2 { data: Option<Vec<u8>> }
impl Guard2 {
    fn take(mut self) -> Vec<u8> { self.data.take().unwrap() }
}
impl Drop for Guard2 {
    fn drop(&mut self) { if let Some(d) = self.data.take() { /* 정리 */ } }
}

// Copy 와 Drop 은 함께 못 씁니다 (해제할 것이 있는데 비트 복사는 모순)
// ManuallyDrop 으로 우회하는 패턴은 FFI 에서 나옵니다 (🔗 f06 · 🔬 d04)

빌림 규칙

let mut s = String::from("안녕");

// ✅ 불변 참조는 여러 개
let r1 = &s;
let r2 = &s;
println!("{r1} {r2}");

// ✅ 가변 참조는 하나
let m = &mut s;
m.push_str(" 세상");

// ❌ 불변과 가변은 함께 못 씁니다
// let r = &s;
// let m = &mut s;      // error[E0502]: cannot borrow `s` as mutable
// println!("{r}");     //   because it is also borrowed as immutable

// ★ 왜 이 규칙인가
//   "읽는 동안 아무도 못 바꾼다" 가 보장되면
//   · 이터레이터 무효화가 없고 (r06)
//   · 데이터 경쟁이 없고 (⚡ e06)
//   · 컴파일러가 값을 레지스터에 캐시해도 안전합니다 (최적화 이득)

참조는 언제까지 살아 있나 (NLL)

let mut s = String::from("안녕");

let r = &s;
println!("{r}");        // ★ r 의 '마지막 사용'이 여기
let m = &mut s;         // ✅ 통과합니다! r 은 이미 끝났으니까
m.push('!');

// 이것을 NLL (non-lexical lifetimes) 이라고 합니다.
// 참조의 수명은 스코프 끝이 아니라 '마지막으로 쓰인 곳'까지입니다.
// → 2018 이전 Rust 의 악명 높은 답답함이 대부분 여기서 사라졌습니다. ★

// 그래서 이런 코드도 됩니다
let mut v = vec![1, 2, 3];
let first = v[0];        // 값을 복사 (참조가 아님)
v.push(4);               // ✅ 문제없음

// 이건 여전히 안 됩니다 (참조를 계속 쓰니까)
// let first = &v[0];
// v.push(4);
// println!("{first}");  // ❌

메서드 시그니처가 곧 동시성 계약

impl Cache {
    fn get(&self, k: &str) -> Option<&Value>;    // 읽기 — 동시에 여럿 가능
    fn insert(&mut self, k: String, v: Value);   // 쓰기 — 배타적
}

// ★ &self 와 &mut self 를 나눠 두면
//   "동시에 호출해도 되는가"가 타입에 적힌 셈이 됩니다.
//   나중에 RwLock 을 씌울 때 그대로 대응됩니다 (⚡ e07).

// 인자를 여러 개 빌릴 때 — 서로 다른 것이면 문제없습니다
fn merge(dst: &mut Vec<u8>, src: &[u8]) { dst.extend_from_slice(src); }
// merge(&mut v, &v);      // ❌ 같은 것을 동시에 가변·불변으로

// 슬라이스를 나눠 각각 가변으로 (병렬 처리의 기초 · ⚡ e05)
let (left, right) = v.split_at_mut(mid);      // ✅ 겹치지 않음이 보장됨
std::thread::scope(|s| {
    s.spawn(|| process(left));
    s.spawn(|| process(right));
});

반환 타입으로 빌림을 끊기

// ❌ 참조를 돌려주면 호출자가 그동안 원본을 못 고칩니다
fn names(&self) -> Vec<&str> { }
let n = cache.names();
// cache.insert(..);        // ❌ n 이 살아 있는 동안 불가

// ✅ 선택지 ① 소유 값을 돌려준다 (복사 비용을 감수)
fn names(&self) -> Vec<String> { }

// ✅ 선택지 ② 이터레이터를 돌려주고 즉시 소비하게 한다
fn names(&self) -> impl Iterator<Item = &str> { }

// ✅ 선택지 ③ 콜백으로 뒤집는다 (내부 이터레이션)
fn for_each_name(&self, f: impl FnMut(&str)) { }

// ★ 라이브러리 API 를 만들 때의 실무 기준
//   · 작고 자주 부름          → 소유 값 (String) — 사용자가 편합니다
//   · 크고 성능이 중요        → 참조·이터레이터 + 문서에 수명 설명
//   · FFI 경계를 넘어간다     → 반드시 소유 값 (🔗 f06)

MIR 위의 흐름 분석

빌림 검사(borrowck)는 소스가 아니라 MIR(중간 표현) 위에서 돕니다 (🔬 d10).

  ① 각 참조가 '살아 있는 지점들'의 집합을 계산 (liveness)
  ② 각 지점에서 어떤 빌림이 활성인지 추적
  ③ 충돌(같은 자리에서 가변+불변, 또는 가변 둘)을 찾으면 에러

# 컴파일러가 보는 것을 직접 보기 (nightly)
cargo +nightly rustc -- -Z dump-mir=main
RUSTC_LOG=rustc_borrowck cargo +nightly build

★ 중요한 성질: borrowck 는 '함수 하나 안에서만' 봅니다.
  함수 경계는 시그니처(라이프타임)만 보고 판단합니다 (o03).
  그래서 시그니처가 정확하면 구현을 바꿔도 호출자가 안 깨집니다.

아직 안 되는 것 — 그리고 우회법

// ★ 유명한 한계: 조건부로 빌림을 반환하는 패턴 (NLL 문제 사례 #3)
// fn get_or_insert<'a>(m: &'a mut HashMap<K,V>, k: K) -> &'a mut V {
//     if let Some(v) = m.get_mut(&k) { return v; }   // ❌ 여기서 빌림이
//     m.insert(k, V::default());                    //    끝나지 않은 것으로 봄
//     m.get_mut(&k).unwrap()
// }

// ✅ 우회 ① entry API (표준 라이브러리가 이걸 위해 존재합니다)
fn get_or_insert<'a>(m: &'a mut HashMap<String, V>, k: String) -> &'a mut V {
    m.entry(k).or_default()
}

// ✅ 우회 ② contains_key 로 먼저 확인 (조회가 두 번)
// ✅ 우회 ③ polonius (차세대 borrowck) 를 기다리기 — 이 패턴을 허용합니다

// ★ 실무 감각: borrowck 가 막는 것의 대부분은 '진짜 문제'입니다.
//   위 사례처럼 '안전한데 못 통과하는' 경우는 손에 꼽을 정도이고,
//   전부 표준 라이브러리에 우회 API 가 마련돼 있습니다.

왜 필요한가 — 댕글링을 막습니다

// ❌ 컴파일러가 이걸 막아야 합니다
// fn longest(a: &str, b: &str) -> &str {
//     if a.len() > b.len() { a } else { b }
// }
//   error[E0106]: missing lifetime specifier
//   help: this function's return type contains a borrowed value, but
//         the signature does not say whether it is borrowed from `a` or `b`

// ✅ "반환값은 a, b 둘 다보다 오래 살지 않는다" 고 적어 줍니다
fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() > b.len() { a } else { b }
}

// 이 표시 덕분에 호출자 쪽에서 이런 코드가 막힙니다
let r;
{
    let tmp = String::from("짧다");
    r = longest(&long, &tmp);      // ❌ tmp 가 곧 죽는데 r 은 밖에 있음
}
// println!("{r}");

생략 규칙 — 안 적어도 되는 경우 ★

// 컴파일러가 자동으로 붙이는 규칙 세 개
//   ① 각 참조 인자에 서로 다른 라이프타임을 준다
//   ② 인자가 참조 하나뿐이면, 반환값도 그것으로 정한다
//   ③ 메서드에 &self 가 있으면, 반환값은 self 로 정한다

fn first(s: &str) -> &str { }              // ② → <'a>(s: &'a str) -> &'a str
impl Doc {
    fn title(&self) -> &str { }            // ③ → &'a self -> &'a str
}

// ★ 이 세 규칙 덕분에 실무 코드의 90% 는 라이프타임을 안 적습니다.
//   적어야 하는 경우는 사실상 둘뿐입니다
//     · 참조 인자가 둘 이상이고 반환값이 참조일 때 (longest)
//     · 구조체가 참조를 필드로 가질 때 (아래)

// 구조체가 참조를 담을 때
struct Parser<'a> {
    input: &'a str,        // "Parser 는 input 보다 오래 못 산다"
    pos: usize,
}
impl<'a> Parser<'a> {
    fn new(input: &'a str) -> Self { Self { input, pos: 0 } }
    fn rest(&self) -> &'a str { &self.input[self.pos..] }
}

처방을 순서대로 시도합니다 ★

① 소유 값으로 바꿔 본다
     &str → String,  &[T] → Vec<T>
     → 90% 는 여기서 끝납니다. 복사 비용은 대개 무시할 수준입니다.

② 참조를 반환하지 말고 인덱스·범위를 반환한다
     fn find(&self) -> &str        →  fn find(&self) -> Range<usize>

③ 콜백으로 뒤집는다 (내부 이터레이션)
     fn items(&self) -> Vec<&T>    →  fn for_each(&self, f: impl FnMut(&T))

④ Rc/Arc 로 공유 소유권을 만든다 (o10)
     여러 곳이 진짜로 같은 값을 오래 봐야 할 때만

⑤ 그래도 안 되면 구조를 바꾼다
     아레나 · 인덱스 기반 (o01)

★ 순서를 지키는 게 중요합니다. ①을 건너뛰고 ④부터 가면
  Rc<RefCell<T>> 로 뒤덮인, 런타임에 패닉하는 코드가 됩니다.

자주 만나는 에러 두 개

# ① 지역 변수를 참조로 반환
error[E0106]: missing lifetime specifier
   fn make() -> &str { let s = String::new(); &s }
help: consider using the `'static` lifetime   ← ❌ 이 조언은 대개 틀립니다
✅ 답: String 을 반환하세요

# ② 빌린 값이 충분히 오래 못 삼
error[E0597]: `tmp` does not live long enough
   |     let r = process(&tmp);
   |                      --- borrowed value does not live long enough
   | }
   | - `tmp` dropped here while still borrowed
   | println!("{r}");
   |            - borrow later used here
✅ 답: tmp 를 더 바깥 스코프로 올리거나, 결과를 소유 값으로 받으세요

# ★ 컴파일러의 help: 가 'static 을 제안하면 의심하세요.
#   대부분 "소유 값으로 바꾸라"가 진짜 답입니다.

변성(variance) — 왜 어떤 건 되고 어떤 건 안 되나

// &'long T 를 &'short T 가 필요한 자리에 넣을 수 있습니다 (공변)
fn takes_short<'s>(x: &'s str) { }
let long: &'static str = "리터럴";
takes_short(long);            // ✅ 더 오래 사는 건 언제나 OK

// 하지만 &mut T 는 T 에 대해 '불변(invariant)' 입니다
// fn f<'a>(x: &mut &'a str, y: &'a str) { *x = y; }
//   → &mut 안의 라이프타임은 늘리지도 줄이지도 못합니다.
//   이걸 허용하면 짧은 참조를 긴 자리에 심을 수 있게 됩니다.

// 정리
//   &'a T          'a 에 공변, T 에 공변
//   &'a mut T      'a 에 공변, T 에 불변  ★ 여기가 에러의 근원
//   fn(T) -> U     T 에 반변, U 에 공변
//   Cell<T>        T 에 불변
//
// PhantomData 로 변성을 직접 지정하는 일은 unsafe 추상화에서 나옵니다 (🔬 d08)

HRTB — 어떤 라이프타임이든

// "어떤 'a 에 대해서든 동작하는 함수"를 받고 싶을 때
fn apply<F>(f: F)
where F: for<'a> Fn(&'a str) -> &'a str      // ★ higher-ranked trait bound
{
    let s = String::from("안녕");
    println!("{}", f(&s));
}
apply(|x| x);           // ✅

// 대부분은 생략해도 컴파일러가 붙여 줍니다
fn apply2<F: Fn(&str) -> &str>(f: F) { }     // 위와 같은 뜻

// 실제로 만나는 자리 — 클로저를 받는 API, serde 의 Deserialize<'de>
// trait Deserialize<'de>: Sized {
//     fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error>;
// }
// → "입력 버퍼에서 빌려 오는 역직렬화"를 표현하기 위한 것입니다.

// 라이프타임의 정체
//   런타임에는 아무것도 남지 않습니다. 타입 검사용 표시일 뿐입니다. ★
//   즉 &'a str 와 &'b str 는 실행 파일에서 완전히 동일합니다 (포인터+길이).

슬라이스의 정체

let v = vec![10, 20, 30, 40, 50];
let s: &[i32] = &v[1..4];        // [20, 30, 40]

// 메모리에는 이것뿐입니다 — 데이터 복사 없음
//   { ptr: v.as_ptr() + 1*4,  len: 3 }
assert_eq!(std::mem::size_of::<&[i32]>(), 16);   // 포인터 8 + 길이 8

// 문자열도 같습니다
let text = String::from("안녕 세상");
let word: &str = &text[0..6];    // "안녕"  (바이트 인덱스 · r06)
assert_eq!(std::mem::size_of::<&str>(), 16);

// 소유 ↔ 빌림 대응표
//   String  → &str
//   Vec<T>  → &[T]
//   Box<[T]> → &[T]
//   [T; N]  → &[T]
// ★ 함수 인자는 항상 오른쪽(빌림)으로 받으세요 — 왼쪽 전부를 받을 수 있습니다

가변 슬라이스와 분할

let mut v = vec![3, 1, 2];
let s: &mut [i32] = &mut v;
s.sort();                          // 제자리 정렬
s[0] = 99;

// 겹치지 않게 둘로 나누기 — 병렬 처리의 기초 ★
let (a, b) = v.split_at_mut(1);    // 둘 다 &mut, 겹치지 않음이 보장됨
a[0] += 1;
b[0] += 1;

// 청크로 나누기
for chunk in v.chunks_mut(2) { chunk.sort(); }
for pair in v.windows(2) { }                    // 겹치는 창 (불변만)

// 채우기·복사 — memcpy 로 최적화됩니다 (⚡ e02)
dst.copy_from_slice(&src);         // 길이가 같아야 함 (T: Copy)
dst.clone_from_slice(&src);        // Clone 이면
buf.fill(0);

// 검색
v.binary_search(&30);              // 정렬돼 있을 때 O(log n)
v.iter().position(|x| *x == 30);   // 선형
v.contains(&30);

호출자가 버퍼를 주게 만들기 ★

// ❌ 매번 새로 할당 — 루프에서 부르면 할당이 병목이 됩니다
fn process(input: &[u8]) -> Vec<u8> { }

// ✅ 출력 버퍼를 받아 재사용하게 하기
fn process_into(input: &[u8], out: &mut Vec<u8>) {
    out.clear();                       // 용량은 유지됩니다 ★
    out.extend(input.iter().map(|b| b ^ 0xFF));
}

let mut buf = Vec::with_capacity(4096);
for chunk in stream {
    process_into(chunk, &mut buf);     // 할당은 첫 회 한 번뿐
    write(&buf)?;
}

// ✅ 둘 다 제공하는 것이 친절합니다 (표준 라이브러리 방식)
pub fn process(input: &[u8]) -> Vec<u8> {
    let mut out = Vec::new();
    process_into(input, &mut out);
    out
}

// ★ 이 패턴이 네이티브 모듈에서 특히 중요합니다.
//   파이썬·Node 에서 초당 수천 번 부르는 함수라면
//   할당 하나가 전체 성능을 좌우합니다 (🐍 y06 · ⚡ e02)

바이트를 안전하게 해석하기

// 네트워크·파일에서 온 바이트를 구조체로 읽기
fn read_header(buf: &[u8]) -> Option<(u32, u16)> {
    if buf.len() < 6 { return None; }              // ★ 길이 검사 먼저
    let len = u32::from_be_bytes(buf[0..4].try_into().ok()?);
    let kind = u16::from_be_bytes(buf[4..6].try_into().ok()?);
    Some((len, kind))
}
// try_into() 로 &[u8] → [u8; 4] 변환 — 길이가 안 맞으면 Err ★

// 엔디안을 명시하세요 (FFI·프로토콜 · 🔗 f03)
u32::from_le_bytes(..);  u32::from_be_bytes(..);
x.to_le_bytes();         x.to_be_bytes();

// 문자열로 해석
let s = std::str::from_utf8(&buf)?;                // 검증 (실패 가능)
let s = String::from_utf8_lossy(&buf);            // 깨진 건 � 로 (실패 없음)

// ❗ unsafe 캐스팅은 정렬 문제로 UB 가 됩니다 (🔬 d03)
// let h: &Header = unsafe { &*(buf.as_ptr() as *const Header) };  // ❌
// ✅ bytemuck · zerocopy 크레이트가 안전하게 해 줍니다

크기를 컴파일 타임에 모르는 타입

// [T] 와 str 은 '크기가 정해지지 않은 타입'(DST) 입니다.
// 그래서 그 자체로는 변수에 담을 수 없습니다.
// let x: [i32];        // ❌ the size for values of type `[i32]`
//                      //    cannot be known at compilation time

// 항상 포인터 뒤에 있어야 합니다 — 그때 길이가 함께 붙습니다 (팻 포인터)
let a: &[i32] = &v;               // 16바이트 (ptr + len)
let b: Box<[i32]> = v.into_boxed_slice();
let c: &str = "안녕";
let d: &dyn Draw = &circle;       // 16바이트 (ptr + vtable) · o06

// 제네릭 기본 제약은 Sized 입니다
fn f<T>(x: T) { }                 // 사실은 T: Sized
fn g<T: ?Sized>(x: &T) { }        // ?Sized 로 풀면 DST 도 받습니다 ★

// 표준 라이브러리 예
//   impl<T: ?Sized> AsRef<T> for &T
//   Box<dyn Error>  ·  Arc<str>  ·  Rc<[T]>

Arc<str> · Box<[T]> 로 메모리 아끼기

use std::sync::Arc;
use std::mem::size_of;

// 자주 쓰는 트릭 — 더 이상 안 늘어날 데이터
size_of::<String>();          // 24 (ptr + cap + len)
size_of::<Box<str>>();        // 16 (ptr + len)  ★ 8바이트 절약
size_of::<Arc<str>>();        // 16

let s: Box<str> = "고정".into();
let shared: Arc<str> = Arc::from("여러 곳에서 공유");
let shared2 = Arc::clone(&shared);          // 카운터만 +1 (o10)

// ★ 실무 효과: 문자열 수백만 개를 담는 인덱스·심볼 테이블에서
//   String → Box<str> 만 바꿔도 메모리가 눈에 띄게 줍니다.
//   (직접 재 보세요 — 데이터 성격에 따라 차이가 큽니다)

// Vec 도 마찬가지
let fixed: Box<[u8]> = vec.into_boxed_slice();
let shared: Arc<[u8]> = Arc::from(vec);      // 여러 스레드가 읽기만 할 때 ★

정의하고 구현하기

trait Shape {
    fn area(&self) -> f64;                     // 구현해야 하는 것

    fn name(&self) -> &str { "도형" }          // 기본 구현 ★
    fn describe(&self) -> String {             // 기본 구현이 다른 걸 부름
        format!("{}의 넓이는 {:.2}", self.name(), self.area())
    }
}

struct Circle { r: f64 }
struct Square { s: f64 }

impl Shape for Circle {
    fn area(&self) -> f64 { std::f64::consts::PI * self.r * self.r }
    fn name(&self) -> &str { "원" }            // 기본 구현을 덮어쓰기
}
impl Shape for Square {
    fn area(&self) -> f64 { self.s * self.s }  // name 은 기본값 "도형"
}

println!("{}", Circle { r: 1.0 }.describe());  // 원의 넓이는 3.14

// 트레이트를 인자로 받기
fn print_area(s: &impl Shape) { println!("{}", s.area()); }
fn print_area2<T: Shape>(s: &T) { }            // 같은 뜻

남의 타입에 내 트레이트 붙이기 ★

// 자바·C# 에서는 불가능한 일입니다
trait Summary {
    fn summary(&self) -> String;
}

impl Summary for String {                  // 표준 타입에 붙이기
    fn summary(&self) -> String {
        self.chars().take(20).collect::<String>() + "…"
    }
}
impl<T: std::fmt::Debug> Summary for Vec<T> {    // 제네릭하게
    fn summary(&self) -> String { format!("{}개 항목", self.len()) }
}

"긴 문장입니다".to_string().summary();
vec![1, 2, 3].summary();

// ★ 고아 규칙 (r09): 트레이트나 타입 중 '하나는 내 것'이어야 합니다.
//   impl Display for Vec<u8>  → ❌ 둘 다 남의 것
//   impl Summary for Vec<u8>  → ✅ 트레이트가 내 것
//   impl Display for MyType   → ✅ 타입이 내 것

// 이 성질을 '확장 트레이트' 패턴이라고 부릅니다.
// itertools · anyhow::Context 등 유명 크레이트가 전부 이걸 씁니다.

테스트를 위한 추상화

// 외부 의존(HTTP · DB · 시계)을 트레이트로 뽑으면 테스트가 쉬워집니다
trait Clock { fn now(&self) -> SystemTime; }

struct SystemClock;
impl Clock for SystemClock { fn now(&self) -> SystemTime { SystemTime::now() } }

struct FixedClock(SystemTime);
impl Clock for FixedClock { fn now(&self) -> SystemTime { self.0 } }

struct Service<C: Clock> { clock: C }
impl<C: Clock> Service<C> {
    fn is_expired(&self, t: SystemTime) -> bool { self.clock.now() > t }
}

#[test]
fn expiry() {
    let s = Service { clock: FixedClock(fixed_time) };   // ★ 시간을 고정
    assert!(s.is_expired(past));
}

// ★ 주의: 모든 것을 트레이트로 뽑지 마세요.
//   구현이 하나뿐인 트레이트는 '간접 층'만 늘립니다.
//   두 번째 구현(테스트용 포함)이 실제로 필요할 때 만드세요.

공개 트레이트를 설계할 때

// ① 메서드를 나중에 추가해도 안 깨지게 — 기본 구현을 주세요
pub trait Codec {
    fn encode(&self, v: &Value) -> Vec<u8>;
    fn name(&self) -> &str { "unknown" }        // 나중에 추가해도 OK
}

// ② 외부에서 구현하지 못하게 막기 (sealed 패턴)
mod private { pub trait Sealed {} }
pub trait Format: private::Sealed { }
impl private::Sealed for Json {}
impl Format for Json {}
// → 사용자는 Format 을 구현할 수 없습니다.
//   나중에 메서드를 추가해도 하위 호환이 깨지지 않습니다 ★

// ③ dyn 으로 쓸 수 있게 유지 (o06)
//   제네릭 메서드나 Self 반환이 있으면 dyn 이 불가능해집니다
pub trait Draw {
    fn draw(&self);                        // ✅ dyn 가능
    // fn clone_box(&self) -> Self;        // ❌ dyn 불가
    fn clone_box(&self) -> Box<dyn Draw>;  // ✅ 이렇게 우회
}

연관 상수와 타입

trait Codec {
    const NAME: &'static str;              // 연관 상수
    type Output;                            // 연관 타입 (r10)
    type Error: std::error::Error;          // 제약도 걸 수 있습니다

    fn decode(&self, b: &[u8]) -> Result<Self::Output, Self::Error>;
}

impl Codec for Json {
    const NAME: &'static str = "json";
    type Output = Value;
    type Error = serde_json::Error;
    fn decode(&self, b: &[u8]) -> Result<Value, serde_json::Error> { }
}

// 쓰는 쪽
fn run<C: Codec>(c: &C, b: &[u8]) -> Result<C::Output, C::Error> {
    println!("{}", C::NAME);
    c.decode(b)
}

// GAT — 연관 타입이 라이프타임을 받을 수 있습니다 (1.65+)
trait Lender {
    type Item<'a> where Self: 'a;
    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>>;
}
// → "빌려 주는 이터레이터"를 표현합니다. 버퍼 재사용 API 에 씁니다.

메서드 해석 순서와 모호성

// 이름이 같은 메서드가 여러 곳에 있을 때
trait Pilot { fn fly(&self); }
trait Wizard { fn fly(&self); }
struct Human;
impl Pilot for Human { fn fly(&self) { println!("조종"); } }
impl Wizard for Human { fn fly(&self) { println!("마법"); } }
impl Human { fn fly(&self) { println!("팔 흔들기"); } }

let h = Human;
h.fly();                        // "팔 흔들기" — 고유 메서드가 우선 ★
Pilot::fly(&h);                 // "조종"
Wizard::fly(&h);                // "마법"
<Human as Wizard>::fly(&h);     // 완전 수식 문법 (연관 함수일 때 필요)

// 컴파일러의 메서드 탐색 순서
//   ① 값 자체의 고유 impl        (Human::fly)
//   ② &self / &mut self 로 자동 참조
//   ③ Deref 를 따라가며 반복      (String → str → …) · o07
//   ④ 스코프에 있는 트레이트의 impl
//
// ★ "메서드가 없다"는 에러의 흔한 원인: 트레이트를 use 하지 않은 것
//   use std::io::Read;         ← 이게 없으면 .read() 가 안 보입니다

두 방식을 나란히

trait Draw { fn draw(&self); }

// ① 제네릭 — 정적 디스패치
fn render_static<T: Draw>(x: &T) { x.draw(); }
//  컴파일러가 타입별로 함수를 복사해 만듭니다 (단형화 · r10)
//  → 호출이 인라인될 수 있고, 비용이 0 입니다

// ② 트레이트 객체 — 동적 디스패치
fn render_dyn(x: &dyn Draw) { x.draw(); }
//  실행 중에 vtable 을 보고 어느 draw 인지 찾습니다
//  → 함수 포인터 한 번 경유 (인라인 불가)

// ★ 결정적 차이: 여러 타입을 한 컬렉션에 담기
let shapes: Vec<Box<dyn Draw>> = vec![
    Box::new(Circle { r: 1.0 }),
    Box::new(Square { s: 2.0 }),        // ✅ 서로 다른 타입이 한 Vec 에
];
for s in &shapes { s.draw(); }

// let v: Vec<impl Draw> = vec![circle, square];   // ❌ 불가능

고르는 기준 ★

// ★ 실무 기준선
//   · 안쪽 루프에서 초당 수백만 번 호출  → 제네릭
//   · 플러그인·핸들러 목록                → dyn
//   · 설정에 따라 구현이 바뀜             → dyn
//   · 라이브러리 공개 API                 → dyn 쪽이 사용자에게 편할 때가 많음
//   · 빌드 시간이 아프다                  → dyn
//
// 실제 비용 감각 (직접 재 보세요 · ⚡ e01)
//   dyn 호출 오버헤드는 보통 나노초 단위입니다.
//   함수 본문이 조금이라도 하는 일이 있으면 차이가 묻힙니다.
//   "dyn 은 느리다"는 대부분 측정 없이 하는 말입니다.

세 번째 선택지 ★

// 구현이 '내가 아는 유한한 집합' 이라면 enum 이 대개 낫습니다
enum Shape { Circle(Circle), Square(Square) }

impl Shape {
    fn area(&self) -> f64 {
        match self {
            Shape::Circle(c) => c.area(),
            Shape::Square(s) => s.area(),
        }
    }
}
let shapes: Vec<Shape> = vec![Shape::Circle(c), Shape::Square(s)];

// ★ enum 의 장점
//   · 힙 할당 없음 (Box 불필요)
//   · 인라인 가능 (dyn 보다 빠름)
//   · 빠짐없음 검사 (r04) — 새 도형을 추가하면 컴파일러가 짚어 줍니다
//   · Clone·PartialEq 를 derive 할 수 있음

// dyn 의 장점
//   · 사용자가 새 구현을 추가할 수 있음 (플러그인)
//   · 내 크레이트를 고치지 않아도 됨

// 판단 한 줄
//   "외부에서 구현을 추가할 수 있어야 하나?"
//     예 → dyn / 아니오 → enum ★
// (enum_dispatch 크레이트가 이 변환을 자동화해 줍니다)

제네릭이 API 를 오염시킬 때

// ❌ 제네릭이 전염됩니다
struct Server<S: Storage, L: Logger, C: Clock> { s: S, l: L, c: C }
// → 쓰는 쪽이 매번 타입 3개를 적어야 하고, 함수 시그니처마다 따라다닙니다

// ✅ 경계에서 dyn 으로 바꿔 가둡니다
struct Server {
    storage: Box<dyn Storage + Send + Sync>,
    logger: Arc<dyn Logger + Send + Sync>,
}
impl Server {
    fn new(s: impl Storage + Send + Sync + 'static) -> Self {
        Self { storage: Box::new(s), .. }     // ★ 생성자만 제네릭
    }
}

// ★ 실무 패턴: '바깥은 제네릭으로 편하게 받고, 안에서는 dyn 으로 저장'
//   빌드 시간이 줄고, 타입 시그니처가 짧아지고, 성능 차이는 대개 무시할 수준입니다.
//   (초당 수백만 호출되는 안쪽 루프만 제네릭으로 남기세요)

팻 포인터 두 워드

&dyn Draw 의 메모리 (64비트)
  ┌──────────────┬──────────────┐
  │ data pointer │ vtable ptr   │   16바이트
  └──────────────┴──────────────┘
                        │
                        ▼
      vtable (정적 데이터 · 타입마다 하나)
        [0] drop_in_place 함수 포인터
        [1] size
        [2] align
        [3] draw 함수 포인터
        [4] … (트레이트 메서드 순서대로)

★ C++ 와 다른 점
  C++ 는 vtable 포인터가 '객체 안'에 들어갑니다 (객체가 8바이트 커짐).
  Rust 는 '참조 쪽'에 붙습니다 → 객체 자체는 커지지 않습니다.
  그래서 같은 타입을 dyn 으로도, 제네릭으로도 비용 없이 쓸 수 있습니다.

비용을 실제로 재기

// criterion 으로 두 방식을 비교 (⚡ e01)
fn bench(c: &mut Criterion) {
    let shapes_dyn: Vec<Box<dyn Shape>> = make_dyn();
    let shapes_enum: Vec<ShapeEnum> = make_enum();

    c.bench_function("dyn", |b| b.iter(||
        shapes_dyn.iter().map(|s| s.area()).sum::<f64>()));
    c.bench_function("enum", |b| b.iter(||
        shapes_enum.iter().map(|s| s.area()).sum::<f64>()));
}

// ★ 결과 해석의 요령 (환경마다 다르니 직접 재세요)
//   · 함수 본문이 아주 짧으면 enum/제네릭이 눈에 띄게 빠릅니다
//     (인라인 + 벡터화가 걸리기 때문 · ⚡ e09)
//   · 본문이 수십 나노초 이상 일하면 차이가 거의 사라집니다
//   · 캐시 지역성이 더 큰 변수입니다 — Box<dyn> 은 힙에 흩어집니다 (⚡ e04)

// 인라인이 걸렸는지 확인
//   cargo asm --lib '내함수'  또는 godbolt.org

Deref — 자동 변환의 정체 ★

fn greet(s: &str) { }
let owned = String::from("안녕");
greet(&owned);          // ★ &String 인데 &str 자리에 들어갑니다

// 이유: String 이 Deref<Target = str> 을 구현하기 때문입니다.
// 컴파일러가 필요할 때 자동으로 &String → &str 로 바꿔 줍니다 (deref coercion)

// 표준 라이브러리의 Deref 사슬
//   String  → str
//   Vec<T>  → [T]
//   Box<T>  → T
//   Rc<T>   → T
//   Arc<T>  → T
//   MutexGuard<T> → T      ★ *guard 로 안을 쓰는 이유

// 그래서 이게 됩니다
let v = vec![3, 1, 2];
v.sort();               // sort 는 [T] 의 메서드인데 Vec 에서 그냥 불림
let b = Box::new(user);
println!("{}", b.name); // Box 를 벗기고 필드 접근

// 직접 구현 — 뉴타입에서 자주 씁니다 (r07)
use std::ops::Deref;
struct Meters(f64);
impl Deref for Meters {
    type Target = f64;
    fn deref(&self) -> &f64 { &self.0 }
}
let m = Meters(3.5);
println!("{}", m.sqrt());     // f64 의 메서드가 그대로 쓰입니다

연산자 트레이트

use std::ops::{Add, Mul, Index, AddAssign, Neg};

#[derive(Debug, Clone, Copy, PartialEq)]
struct Vec2 { x: f64, y: f64 }

impl Add for Vec2 {
    type Output = Vec2;
    fn add(self, o: Vec2) -> Vec2 { Vec2 { x: self.x + o.x, y: self.y + o.y } }
}
impl Mul<f64> for Vec2 {                  // 스칼라 곱 (오른쪽 타입이 다름)
    type Output = Vec2;
    fn mul(self, k: f64) -> Vec2 { Vec2 { x: self.x * k, y: self.y * k } }
}
impl AddAssign for Vec2 {                 // +=
    fn add_assign(&mut self, o: Vec2) { self.x += o.x; self.y += o.y; }
}
impl Neg for Vec2 { type Output = Vec2; fn neg(self) -> Vec2 { self * -1.0 } }

let c = Vec2 { x:1.0, y:2.0 } + Vec2 { x:3.0, y:4.0 };
let d = c * 2.0;

// 인덱싱
impl Index<usize> for Grid {
    type Output = [u8];
    fn index(&self, row: usize) -> &[u8] { &self.data[row*self.w..(row+1)*self.w] }
}
grid[2][3];

// 비교는 derive 로 (PartialEq, PartialOrd)
// == 는 PartialEq, < 는 PartialOrd 가 담당합니다

FFI 핸들을 감싸는 정석 패턴 ★

// C 라이브러리의 핸들을 Rust 타입으로 감쌉니다 (🔗 f08)
pub struct Decoder {
    raw: *mut ffi::Decoder,        // C 가 준 포인터
}

impl Decoder {
    pub fn new() -> Result<Self, Error> {
        let raw = unsafe { ffi::decoder_create() };
        if raw.is_null() { return Err(Error::Alloc); }
        Ok(Decoder { raw })
    }
    pub fn decode(&mut self, input: &[u8]) -> Result<Vec<u8>, Error> { }
}

impl Drop for Decoder {
    fn drop(&mut self) {
        unsafe { ffi::decoder_destroy(self.raw) };    // ★ 반드시 해제됩니다
    }
}

// Send/Sync 를 손으로 붙여야 할 수도 있습니다 (⚡ e06 · 🔬 d08)
unsafe impl Send for Decoder {}    // C 라이브러리가 스레드 안전하다면

// ★ 이 패턴이 "안전 추상화"의 기본형입니다.
//   사용자는 unsafe 를 한 줄도 쓰지 않고, 해제를 빠뜨릴 수도 없습니다.

Drop 을 쓸 때의 실무 규칙

// ① 실패할 수 있는 정리는 명시 메서드로도 제공하세요
impl Writer {
    pub fn finish(mut self) -> io::Result<()> {     // 에러를 받을 수 있음
        self.flush()?;
        self.done = true;
        Ok(())
    }
}
impl Drop for Writer {
    fn drop(&mut self) {
        if !self.done { let _ = self.flush(); }      // ★ 에러를 삼킬 수밖에 없음
    }
}

// ② Drop 안에서 블로킹·await 하지 마세요 (⚡ e08)
//    async 런타임 안에서 Drop 이 블로킹하면 전체가 멈춥니다.

// ③ 순환 참조가 있으면 Drop 이 안 불립니다 (Rc · o10)

// ④ 프로세스가 abort 하면 Drop 이 안 불립니다
//    std::process::exit()  ·  panic = "abort" 프로파일 (🛠️ b06)
//    → 파일 flush 를 Drop 에만 의존하지 마세요

// ⑤ 테스트로 확인하기
#[test]
fn drops_once() {
    let counter = Arc::new(AtomicUsize::new(0));
    { let _g = Guard(counter.clone()); }
    assert_eq!(counter.load(Ordering::SeqCst), 1);
}

언제 자동으로 벗겨지나

// deref coercion 이 일어나는 자리
//   ① 함수 인자로 넘길 때        &String → &str
//   ② 메서드 호출의 수신자        v.sort() 에서 &Vec → &[T]
//   ③ 명시적 & 표현식            let s: &str = &owned;

// 일어나지 않는 자리 ★
//   · 제네릭 타입 매칭
fn f<T: AsRef<str>>(x: T) { }
// f(&owned_string) 은 되지만
fn g<T>(x: &T) { }
// g::<str>(&owned) 는 안 됩니다 — T 를 String 으로 추론하고 끝

//   · 트레이트 구현 매칭
// impl Trait for str {} 가 있어도 String 이 자동으로 그 impl 을 쓰진 않습니다

// 여러 단계도 따라갑니다
let b: Box<String> = Box::new("안녕".into());
let s: &str = &b;                 // Box<String> → String → str  ★ 두 단계

// DerefMut 도 같은 규칙 (&mut 쪽)
// Deref 는 '싸야' 합니다 — 안에서 계산하면 성능 함정이 됩니다

Drop 순서 · 패닉 · 언와인딩

// 패닉이 나면 스택을 되감으며 Drop 이 호출됩니다 (unwinding)
// → RAII 가 패닉 상황에서도 동작하는 이유입니다

// 하지만 두 경우엔 Drop 이 안 불립니다
//   ① panic = "abort" 프로파일 (🛠️ b06 · 바이너리가 작아집니다)
//   ② Drop 안에서 다시 패닉 → 즉시 abort

// 이미 패닉 중인지 확인
impl Drop for X {
    fn drop(&mut self) {
        if std::thread::panicking() {
            return;                    // ★ 패닉 중엔 정리를 건너뜀
        }
        self.commit();
    }
}

// ★ FFI 에서 결정적으로 중요합니다 (🔗 f09)
//   패닉이 C 코드를 가로질러 되감기면 정의되지 않은 동작입니다.
//   extern "C" 함수는 반드시 catch_unwind 로 감싸세요.
extern "C" fn callback() {
    let _ = std::panic::catch_unwind(|| { /* Rust 코드 */ });
}

Result 와 ?

// enum Result<T, E> { Ok(T), Err(E) }

fn read_config(path: &str) -> Result<String, std::io::Error> {
    let s = std::fs::read_to_string(path)?;    // ★ 실패면 즉시 Err 반환
    Ok(s)
}

// ? 가 없다면 이렇게 써야 합니다
fn read_config_verbose(path: &str) -> Result<String, std::io::Error> {
    match std::fs::read_to_string(path) {
        Ok(s) => Ok(s),
        Err(e) => return Err(e),
    }
}

// 연쇄로 쓰면 진가가 드러납니다
fn load() -> Result<Config, Error> {
    let raw = std::fs::read_to_string("config.toml")?;
    let cfg: Config = toml::from_str(&raw)?;      // 다른 에러 타입인데도 됨 ★
    cfg.validate()?;
    Ok(cfg)
}
// ? 는 From<다른에러> for Error 를 자동으로 씁니다 (o07)

// Option 에도 씁니다
fn first_char(s: &str) -> Option<char> {
    let c = s.chars().next()?;      // None 이면 즉시 None 반환
    Some(c.to_ascii_uppercase())
}

파이썬 예외와 비교

# 파이썬 — 어떤 예외가 날지 시그니처에 없습니다
def load():
    raw = open("config.toml").read()     # FileNotFoundError?
    return parse(raw)                    # ValueError? KeyError?

try:
    cfg = load()
except Exception as e:                   # 무엇을 잡는지 모호해집니다
    ...

기준: 호출자가 대응할 수 있는가 ★

// ★ 한 줄 기준
//   "이건 프로그래머의 버그인가, 환경의 문제인가?"
//     버그   → panic!  (고쳐야 할 코드가 있다)
//     환경   → Result  (호출자가 재시도·대체·보고할 수 있다)

// 라이브러리라면 panic 을 문서에 적으세요
/// # 패닉
/// `idx` 가 길이 이상이면 패닉합니다.
pub fn get(&self, idx: usize) -> &T { &self.data[idx] }

// 패닉을 잡을 수도 있습니다 (경계에서만 · 🔗 f09)
let r = std::panic::catch_unwind(|| risky());
// ★ 일반 흐름 제어에 쓰지 마세요. FFI·서버 워커 격리용입니다.

에러를 잃지 않고 전달하기

// ❌ 원인이 사라집니다
fn load() -> Result<Config, String> {
    std::fs::read_to_string(p).map_err(|_| "읽기 실패".to_string())?;
}
// → "읽기 실패" 만 남고 '어느 파일인지 · 권한인지 없는 건지' 가 사라짐

// ✅ 맥락을 더하되 원인을 보존 (o09 에서 자세히)
use anyhow::Context;
fn load(p: &Path) -> anyhow::Result<Config> {
    let raw = std::fs::read_to_string(p)
        .with_context(|| format!("설정 파일 읽기 실패: {}", p.display()))?;
    let cfg = toml::from_str(&raw)
        .with_context(|| "설정 파싱 실패")?;
    Ok(cfg)
}

// 출력 예
//   Error: 설정 파일 읽기 실패: /etc/app.toml
//
//   Caused by:
//       No such file or directory (os error 2)      ★ 원인이 남습니다

// 백트레이스 켜기
//   RUST_BACKTRACE=1 cargo run

Try 트레이트

// x? 는 대략 이렇게 펼쳐집니다
match std::ops::Try::branch(x) {
    ControlFlow::Continue(v) => v,
    ControlFlow::Break(r) => return FromResidual::from_residual(r),
}

// Result 의 경우 실질적으로
match x {
    Ok(v) => v,
    Err(e) => return Err(From::from(e)),      // ★ From 변환이 여기서
}

// 그래서 이런 것이 가능합니다
struct MyErr;
impl From<std::io::Error> for MyErr { }
impl From<std::num::ParseIntError> for MyErr { }

fn f() -> Result<(), MyErr> {
    let s = std::fs::read_to_string("a")?;    // io::Error → MyErr
    let n: i32 = s.trim().parse()?;           // ParseIntError → MyErr
    Ok(())
}

// 비용: 없습니다. 분기 하나입니다.
// Result 는 예외 테이블도, 언와인딩도 쓰지 않습니다 ★
// → 그래서 '에러가 자주 나는 경로'도 빠릅니다 (C++ 예외와 반대)

Result 의 크기가 성능에 미치는 영향

use std::mem::size_of;

size_of::<Result<(), std::io::Error>>();      // 8  (io::Error 는 박싱돼 있음)
size_of::<Result<u64, BigError>>();           // BigError 가 200바이트면 208 ★

// ❗ 성공 경로도 이 크기를 냅니다 — 반환마다 200바이트를 복사합니다
// ✅ 에러를 박싱하세요
enum MyError { Io(std::io::Error), Parse(Box<ParseDetail>) }
type Result<T> = std::result::Result<T, Box<MyError>>;

// 확인
//   cargo clippy 의 result_large_err 린트 (기본 128바이트 이상 경고)
//   cargo +nightly rustc -- -Zprint-type-sizes | grep Result

// ★ 실무 효과: 파서·직렬화처럼 작은 함수를 초당 수백만 번 부르는 코드에서
//   Result 크기를 줄이는 것만으로 눈에 띄게 빨라지는 경우가 있습니다.
//   (직접 재 보세요 — ⚡ e01)

// #[must_use] 로 무시를 막기
#[must_use = "이 결과를 확인하세요"]
pub fn try_send(&self) -> Result<(), SendError> { }

thiserror — 라이브러리용 ★

[dependencies]
thiserror = "2"

use thiserror::Error;

#[derive(Error, Debug)]
pub enum ConfigError {
    #[error("설정 파일을 읽을 수 없습니다: {path}")]
    Read { path: String, #[source] source: std::io::Error },

    #[error("TOML 문법 오류")]
    Parse(#[from] toml::de::Error),          // ★ From 이 자동 생성 → ? 로 변환됨

    #[error("필수 항목이 없습니다: {0}")]
    Missing(String),

    #[error("포트 번호가 범위를 벗어남: {0} (1~65535)")]
    BadPort(u32),
}

pub type Result<T> = std::result::Result<T, ConfigError>;

// 쓰는 쪽
fn load(p: &str) -> Result<Config> {
    let raw = std::fs::read_to_string(p)
        .map_err(|e| ConfigError::Read { path: p.into(), source: e })?;
    let cfg: Config = toml::from_str(&raw)?;      // #[from] 덕분에 자동 변환
    Ok(cfg)
}

// ★ 왜 라이브러리는 구체 타입인가
//   사용자가 match 로 '어떤 실패인지' 구분해 대응할 수 있어야 합니다.
//   Box<dyn Error> 를 돌려주면 문자열 비교밖에 못 합니다.

anyhow — 애플리케이션용 ★

[dependencies]
anyhow = "1"

use anyhow::{Context, Result, bail, ensure};

fn run(path: &str) -> Result<()> {           // Result<(), anyhow::Error>
    let raw = std::fs::read_to_string(path)
        .with_context(|| format!("설정 읽기 실패: {path}"))?;    // 맥락 추가 ★

    let cfg: Config = toml::from_str(&raw).context("TOML 파싱 실패")?;

    ensure!(cfg.port > 0, "포트는 0보다 커야 합니다 (받은 값: {})", cfg.port);
    if cfg.hosts.is_empty() { bail!("호스트 목록이 비었습니다"); }

    Ok(())
}

fn main() -> Result<()> {
    run("app.toml")
}

// 출력
//   Error: 설정 읽기 실패: app.toml
//
//   Caused by:
//       No such file or directory (os error 2)

// ★ anyhow 의 장점
//   · 어떤 에러 타입이든 ? 로 받습니다 (타입을 안 만들어도 됨)
//   · 맥락을 층층이 쌓아 원인 사슬을 만듭니다
//   · 백트레이스를 자동으로 담습니다 (RUST_BACKTRACE=1)
//   단점: 사용자가 종류별로 대응할 수 없습니다 → 라이브러리에는 부적합

파이썬·Node 로 나갈 에러 ★

// 내부는 thiserror 로 잘 나눠 두고
#[derive(Error, Debug)]
pub enum CoreError {
    #[error("입력이 비었습니다")]              Empty,
    #[error("길이 초과: {0} > {1}")]            TooLong(usize, usize),
    #[error("인코딩 오류")]                    Encoding(#[from] std::str::Utf8Error),
}

// 경계에서 그 언어의 예외로 변환합니다
#[cfg(feature = "python")]
impl From<CoreError> for pyo3::PyErr {
    fn from(e: CoreError) -> Self {
        use pyo3::exceptions::*;
        match e {
            CoreError::Empty => PyValueError::new_err(e.to_string()),
            CoreError::TooLong(..) => PyOverflowError::new_err(e.to_string()),
            CoreError::Encoding(_) => PyUnicodeDecodeError::new_err(e.to_string()),
        }
    }
}
// → 파이썬 쪽에서 except ValueError 로 자연스럽게 잡힙니다 (🐍 y08)

// ★ 원칙: 에러 '종류'를 언어 경계에서 잃지 마세요.
//   전부 RuntimeError 로 던지면 쓰는 사람이 대응할 수 없습니다.

C ABI 로 나갈 때는 에러 코드

// C 에는 Result 가 없습니다 → 정수 코드 + 마지막 메시지 (🔗 f09)
#[repr(i32)]
pub enum Code { Ok = 0, Empty = 1, TooLong = 2, Internal = 99 }

thread_local! {
    static LAST_ERROR: std::cell::RefCell<String> = Default::default();
}

#[no_mangle]
pub extern "C" fn my_process(input: *const u8, len: usize) -> i32 {
    let r = std::panic::catch_unwind(|| {          // ★ 패닉 차단 (🔗 f09)
        let s = unsafe { std::slice::from_raw_parts(input, len) };
        core_process(s)
    });
    match r {
        Ok(Ok(_)) => Code::Ok as i32,
        Ok(Err(e)) => { set_last_error(e.to_string()); code_of(&e) }
        Err(_) => { set_last_error("내부 패닉".into()); Code::Internal as i32 }
    }
}

#[no_mangle]
pub extern "C" fn my_last_error(buf: *mut u8, cap: usize) -> usize { }

직접 구현하면 이렇게 됩니다

use std::fmt;

#[derive(Debug)]
pub struct MyError { msg: String, source: Option<Box<dyn std::error::Error + Send + Sync>> }

impl fmt::Display for MyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.msg)        // ★ 자기 것만 씁니다 (원인은 source 로)
    }
}

impl std::error::Error for MyError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.source.as_ref().map(|b| &**b as _)
    }
}

// ★ Display 에 원인까지 넣지 마세요 — 사슬을 출력할 때 중복됩니다
//   ❌ write!(f, "{}: {}", self.msg, self.source)
//   ✅ write!(f, "{}", self.msg)   + source() 구현

// thiserror 가 만들어 주는 것이 정확히 이 코드입니다.
// #[source] · #[from] 이 source() 구현을 생성합니다.

에러 설계 체크리스트 ★

□ 에러 타입이 작은가 (128바이트 이하 · o08)
    큰 필드는 Box 로 감싸세요

□ Send + Sync 인가
    스레드·async 를 쓰면 필수입니다 (⚡ e06)
    Box<dyn Error> 가 아니라 Box<dyn Error + Send + Sync>

□ #[non_exhaustive] 를 붙였는가 (라이브러리)
    나중에 배리언트를 추가해도 사용자 코드가 안 깨집니다 (r08)

□ 원인을 보존하는가 (#[source] / #[from])
    map_err(|_| "실패") 는 조사 불가능한 로그를 만듭니다

□ 메시지가 소문자로 시작하고 마침표가 없는가
    Rust 관례: "failed to read config"  (상위가 이어 붙이기 좋게)
    한글이면 "설정 파일을 읽지 못했습니다" 정도로 통일

□ 민감 정보가 들어가지 않는가
    비밀번호·토큰이 에러 메시지로 로그에 남는 사고가 흔합니다 ★

□ 재시도 가능한 실패를 구분할 수 있는가
    fn is_retryable(&self) -> bool 같은 메서드를 두면 호출자가 편합니다

Box — 힙에 하나 두기

let b = Box::new(42);          // 힙에 값, 스택엔 포인터 8바이트
println!("{}", *b);            // 역참조 (Deref 로 대개 생략됨)

// ① 재귀 타입 — 크기를 정할 수 있게 ★
enum List { Cons(i32, Box<List>), Nil }
//   Box 없이는 "무한 크기" 라 컴파일 안 됩니다

struct Node { value: i32, next: Option<Box<Node>> }   // 링크드 리스트

// ② 큰 값을 옮길 때 (복사 비용 회피 · r05)
fn make() -> Box<[u8; 1_000_000]> { Box::new([0; 1_000_000]) }

// ③ 트레이트 객체 (o06)
let d: Box<dyn Draw> = Box::new(circle);

// ④ 에러 타입 (o08 · o09)
Box<dyn std::error::Error + Send + Sync>

// Box 는 '소유권이 하나'라는 규칙을 그대로 지킵니다.
// 그래서 성능 비용이 사실상 없습니다 (역참조 한 번).

Rc · Arc — 주인이 여럿

use std::rc::Rc;
use std::sync::Arc;

let a = Rc::new(vec![1, 2, 3]);
let b = Rc::clone(&a);          // ★ 데이터 복사가 아니라 카운터 +1
println!("{}", Rc::strong_count(&a));   // 2
// 마지막 Rc 가 사라질 때 데이터가 해제됩니다

// Rc  — 단일 스레드 전용 (카운터가 원자 연산이 아니라 빠름)
// Arc — 여러 스레드 (원자 카운터 · ⚡ e06)
let shared = Arc::new(config);
std::thread::spawn({
    let c = Arc::clone(&shared);
    move || use_config(&c)
});

// ★ 중요: Rc/Arc 안의 값은 '불변'입니다
// let mut v = Rc::new(vec![1]);
// v.push(2);              // ❌ Rc<Vec> 를 통해 고칠 수 없습니다

// 고치려면 안쪽 가변성이 필요합니다 ↓
Rc<RefCell<T>>        // 단일 스레드
Arc<Mutex<T>>         // 멀티 스레드 ★ 가장 흔한 조합 (⚡ e07)
Arc<RwLock<T>>        // 읽기가 훨씬 많을 때

// 순환 참조 끊기 — Weak
use std::rc::Weak;
struct Node { parent: Weak<Node>, children: Vec<Rc<Node>> }
// Weak 는 카운트를 올리지 않습니다. upgrade() 로 Option<Rc> 를 얻습니다.

먼저 대안을 검토합니다 ★

// ① 데이터를 나눠 준다 (공유하지 않기) — 가장 좋은 답
let (a, b) = data.split_at_mut(mid);      // o02
rayon 의 par_chunks_mut                    // ⚡ e05

// ② 메시지로 주고받는다 (채널)
let (tx, rx) = std::sync::mpsc::channel();
// "메모리를 공유해 소통하지 말고, 소통해서 메모리를 공유하라"

// ③ 읽기 전용으로 공유한다
let shared = Arc::new(big_readonly_data);  // Mutex 불필요 ★

// ④ 원자 타입으로 충분한가
let counter = Arc::new(AtomicU64::new(0));
counter.fetch_add(1, Ordering::Relaxed);   // Mutex 보다 훨씬 쌈

// ⑤ 그래도 필요하면
let state = Arc::new(Mutex::new(State::new()));

// ★ 순서를 지키면 Mutex 를 쓸 일이 절반으로 줍니다.
//   Rust 는 ①②③ 을 안전하게 쓸 수 있게 만들어 둔 언어입니다 (⚡ e06).

락을 쓸 때의 규칙

// ① 락 범위를 최소로
// ❌
let mut s = state.lock().unwrap();
let result = expensive_io(&s.config);      // 락을 잡은 채 I/O ★ 최악
s.results.push(result);

// ✅
let config = { state.lock().unwrap().config.clone() };   // 락 즉시 해제
let result = expensive_io(&config);
state.lock().unwrap().results.push(result);

// ② 락을 잡은 채 다른 락을 잡지 마세요 (데드락)
//    꼭 필요하면 '항상 같은 순서로' 잡으세요

// ③ async 안에서 std::sync::Mutex 를 await 너머로 들고 있지 마세요 (⚡ e08)
//    → tokio::sync::Mutex 를 쓰거나, await 전에 놓으세요

// ④ 락 오염(poisoning) — 락을 든 스레드가 패닉하면
let g = m.lock().unwrap_or_else(|e| e.into_inner());   // 무시하고 진행
//    parking_lot 크레이트는 오염 개념이 없어 더 단순하고 빠릅니다

// ⑤ 데드락 진단
//    RUST_BACKTRACE=1 + gdb thread apply all bt
//    parking_lot 의 deadlock_detection feature

UnsafeCell — 유일한 예외

// Rust 의 핵심 가정: &T 가 있으면 그 값은 절대 안 바뀐다
// → 컴파일러가 값을 레지스터에 캐시하고 재정렬해도 안전합니다.
//
// UnsafeCell<T> 만이 이 가정에서 제외됩니다. ★
// Cell · RefCell · Mutex · RwLock · Atomic* 전부 내부적으로 UnsafeCell 입니다.

pub struct Cell<T> { value: UnsafeCell<T> }

// 직접 쓸 일은 거의 없지만, unsafe 추상화를 만들 때 필요합니다 (🔬 d08)
struct MyCell<T> { v: std::cell::UnsafeCell<T> }
impl<T: Copy> MyCell<T> {
    fn get(&self) -> T { unsafe { *self.v.get() } }
    fn set(&self, x: T) { unsafe { *self.v.get() = x } }
}
// ❗ 이 타입은 Sync 가 아니어야 합니다 (UnsafeCell 이 자동으로 !Sync)
//    아니면 두 스레드가 동시에 set 해 데이터 경쟁이 납니다

// 확인: Cell 은 Send 지만 Sync 가 아닙니다
// Mutex 는 둘 다입니다 (락으로 보호하니까)

Rc 의 메모리 배치와 함정

Rc<T> 의 힙 배치
  ┌──────────┬──────────┬─────────┐
  │ strong   │ weak     │  T      │
  │ (usize)  │ (usize)  │         │
  └──────────┴──────────┴─────────┘
        ▲
     Rc<T> = 이 블록을 가리키는 포인터 하나 (8바이트)

★ 실무에서 알아야 할 것
  · T 가 해제되는 시점: strong == 0
  · 블록 자체가 해제되는 시점: strong == 0 && weak == 0
    → Weak 가 살아 있으면 메모리 블록은 남습니다 (T 는 이미 해제됨)
  · 순환 참조가 있으면 strong 이 0 이 안 되어 '진짜로 샙니다' ★
    Rust 가 막아 주지 않는 몇 안 되는 누수입니다

# 누수 확인
#   Rc::strong_count / Arc::strong_count 를 로그로 찍기
#   valgrind --leak-check=full  (리눅스)
#   Miri 는 누수를 기본으로 잡아 줍니다 (🔬 d07)

기본 문법과 캡처

let add = |a: i32, b: i32| a + b;
let add = |a, b| a + b;              // 타입 추론
let square = |x| { let y = x * x; y };

// 바깥 값을 자동으로 가져옵니다 (캡처)
let factor = 3;
let scale = |x| x * factor;          // factor 를 빌림
println!("{}", scale(5));            // 15

// move — 소유권을 가져가기 ★
let name = String::from("현우");
let greet = move || println!("안녕 {name}");
// println!("{name}");               // ❌ name 은 클로저가 가져갔습니다
greet();

// 스레드에 넘길 때는 대개 move 가 필요합니다 (o03 · ⚡ e07)
std::thread::spawn(move || { use_data(data) });

// 이터레이터에서 가장 많이 씁니다 (o12)
v.iter().map(|x| x * 2).filter(|x| *x > 5).collect::<Vec<_>>();
v.sort_by_key(|u| u.age);
v.retain(|x| x.active);

세 종류의 차이 ★

let s = String::from("안녕");

let f_fn      = || println!("{s}");        // Fn      — 읽기만
let mut n = 0;
let f_fnmut   = || { n += 1; };            // FnMut   — 바깥을 고침
let f_fnonce  = move || drop(s);           // FnOnce  — 소유권을 소모

// 포함 관계: Fn ⊂ FnMut ⊂ FnOnce
//   Fn 인 클로저는 FnMut 자리에도, FnOnce 자리에도 들어갑니다 ★

// 인자로 받을 때 — '가장 느슨한 것'을 받으세요
fn call_once(f: impl FnOnce()) { f(); }         // 가장 넓게 받힘
fn call_many(f: impl Fn()) { f(); f(); }        // 여러 번 부를 때만
fn accumulate(mut f: impl FnMut(i32)) { for i in 0..3 { f(i); } }

// 함수 포인터도 받아집니다
fn double(x: i32) -> i32 { x * 2 }
let v: Vec<i32> = (1..4).map(double).collect();      // ✅ fn 은 Fn 을 구현

어떤 형태로 받을 것인가

// ① 즉시 호출하고 버림 → impl FnOnce / impl FnMut (제네릭 · 빠름)
pub fn with_lock<R>(&self, f: impl FnOnce(&mut State) -> R) -> R {
    let mut g = self.state.lock().unwrap();
    f(&mut g)                       // ★ 락 범위를 API 가 강제합니다 (o10)
}
bus.with_lock(|s| s.count += 1);

// ② 저장해 두고 나중에 여러 번 → Box<dyn Fn>
pub fn subscribe(&mut self, f: Box<dyn Fn(&Event) + Send + Sync>) { }

// ③ 진행률 보고 — 없어도 되게
pub fn process(&self, data: &[u8], on_progress: Option<&dyn Fn(f32)>) { }
// 또는 기본값을 주는 두 함수로 나누기 (r03 · 기본 인자가 없으므로)

// ④ FFI 로 넘길 콜백은 함수 포인터 + 사용자 데이터 (🔗 f07)
pub type Callback = extern "C" fn(progress: f32, user: *mut std::ffi::c_void);

// ★ 실무 기준
//   내부용·성능 중요        → impl Fn (제네릭)
//   저장·플러그인·경계 통과 → Box<dyn Fn>

Send · Sync · 'static 을 언제 요구하나

// 스레드로 넘어가면 필요합니다 (⚡ e06)
fn spawn(f: impl FnOnce() + Send + 'static) { }

// 여러 스레드가 동시에 부르면 Sync 도
fn register(f: impl Fn(&Event) + Send + Sync + 'static) { }

// ★ 'static 은 "빌린 것이 없다"는 뜻입니다 (o03)
//   클로저가 지역 변수를 빌리면 만족하지 못합니다 → move 로 해결

// 요구를 최소화하는 것이 친절한 API 입니다
// ❌ 항상 Send + Sync + 'static 을 요구
// ✅ 실제로 스레드를 쓸 때만

// 스코프 스레드를 쓰면 'static 이 필요 없습니다 (⚡ e07)
std::thread::scope(|s| {
    s.spawn(|| use_local(&local));       // ✅ 빌려도 됩니다
});

// 파이썬 콜백을 받을 때 (🐍 y09)
//   PyO3 의 Py<PyAny> 는 Send 지만 호출하려면 GIL 이 필요합니다
//   → 다른 스레드로 넘길 때 규칙이 따로 있습니다

익명 구조체 + 트레이트 구현

let factor = 3;
let scale = move |x: i32| x * factor;

// 컴파일러가 대략 이렇게 만듭니다
struct __Closure1 { factor: i32 }            // 캡처한 것이 필드가 됩니다
impl Fn<(i32,)> for __Closure1 {
    fn call(&self, (x,): (i32,)) -> i32 { x * self.factor }
}

// 크기는 '캡처한 것들의 합'입니다
let a = || ();                       // 0바이트 (ZST) ★
let b = move || factor;              // 4바이트
let c = move || big_vec;             // 24바이트 (Vec 이동)
println!("{}", std::mem::size_of_val(&a));

// ★ 성능 의미
//   · 캡처가 없으면 크기 0 → 넘기는 비용도 0
//   · impl Fn 으로 받으면 인라인됩니다 (⚡ e03)
//   · Box<dyn Fn> 은 힙 할당 + 간접 호출 (o06 과 같은 트레이드오프)

캡처 규칙의 세부

// 컴파일러는 '가장 약한 캡처'를 고릅니다
let v = vec![1, 2, 3];
let f = || println!("{}", v.len());   // &v 로 충분 → Fn
let g = || v.len();                    // 같음
let h = move || v;                     // 값이 필요 → FnOnce

// move 를 붙여도 Copy 타입은 복사됩니다
let n = 5;
let f = move || n;                     // n 은 여전히 쓸 수 있습니다 (i32 는 Copy)

// 2021 에디션의 필드 단위 캡처 (r01)
struct S { a: String, b: String }
let s = S { .. };
let f = move || println!("{}", s.a);   // ★ s.a 만 가져갑니다
println!("{}", s.b);                   // ✅ 2021 부터 가능 (2018 은 에러)

// 강제로 전체를 캡처하려면
let f = move || { let _ = &s; println!("{}", s.a); };

// 클로저에서 재귀하기 — 직접은 안 됩니다
fn fib(n: u64) -> u64 { if n < 2 { n } else { fib(n-1) + fib(n-2) } }
// 클로저로 재귀하려면 Box<dyn Fn> + Rc 또는 별도 fn 을 쓰세요

세 가지 시작점 ★

let v = vec![1, 2, 3];

v.iter()        // &T      — 빌려 보기       (v 는 그대로)
v.iter_mut()    // &mut T  — 고치기
v.into_iter()   // T       — 가져가기        (v 를 소모)

// for 문은 사실 이 셋의 문법 설탕입니다
for x in &v { }          // v.iter()
for x in &mut v { }      // v.iter_mut()
for x in v { }           // v.into_iter()   ★ v 를 못 쓰게 됩니다

// 자주 쓰는 어댑터 (지연 — 아직 아무 일도 안 함)
v.iter()
 .map(|x| x * 2)              // 변환
 .filter(|x| *x > 2)          // 거르기
 .filter_map(|x| f(x).ok())   // 변환 + 거르기 한 번에 ★
 .enumerate()                 // (인덱스, 값)
 .zip(other.iter())           // 두 개 동시에
 .take(5)  .skip(2)  .step_by(2)
 .rev()  .chain(other)  .flatten()
 .take_while(|x| *x < 10)
 .peekable()                  // 다음 것을 미리 보기
 .inspect(|x| println!("{x:?}"))   // 디버깅용 ★

소비자 — 여기서 실제로 돕니다

let v = vec![1, 2, 3, 4];

v.iter().sum::<i32>();               // 10
v.iter().product::<i32>();
v.iter().count();
v.iter().min();  v.iter().max();
v.iter().max_by_key(|x| x.abs());
v.iter().fold(0, |acc, x| acc + x);  // 임의의 누적 ★
v.iter().reduce(|a, b| a.max(b));

v.iter().any(|x| *x > 3);            // 하나라도 (조기 종료)
v.iter().all(|x| *x > 0);            // 전부 (조기 종료)
v.iter().find(|x| **x > 2);          // 첫 번째
v.iter().position(|x| *x == 3);      // 인덱스
v.iter().for_each(|x| println!("{x}"));

// collect — 무엇으로 모을지 타입이 정합니다 (r02)
let v2: Vec<i32> = it.collect();
let s: String = chars.collect();
let m: HashMap<_, _> = pairs.collect();
let set: HashSet<_> = it.collect();
let r: Result<Vec<_>, _> = results.collect();    // 하나라도 Err 면 Err ★

// 정렬은 슬라이스 메서드입니다 (이터레이터가 아님)
let mut v2: Vec<_> = it.collect();
v2.sort_unstable();                  // 안정성이 필요 없으면 이쪽이 빠름
v2.sort_by_key(|u| u.age);
v2.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap());

체인이 길어지면 나누세요

// ❌ 한 줄에 여덟 단계 — 디버깅이 지옥입니다
let r: Vec<_> = data.iter().filter(|x| x.ok).map(|x| &x.name)
    .filter(|n| n.len() > 3).map(|n| n.to_uppercase())
    .filter(|n| !seen.contains(n)).take(10).collect();

// ✅ 의미 단위로 이름을 붙입니다
let valid = data.iter().filter(|x| x.ok);
let names = valid.map(|x| x.name.to_uppercase());
let fresh: Vec<_> = names.filter(|n| !seen.contains(n)).take(10).collect();
// ★ 중간 변수를 만들어도 지연 평가라 성능 비용이 없습니다

// 디버깅 — inspect 를 끼워 넣기
let r: Vec<_> = data.iter()
    .inspect(|x| eprintln!("입력: {x:?}"))
    .filter(|x| x.ok)
    .inspect(|x| eprintln!("통과: {x:?}"))
    .collect();

// 타입이 헷갈릴 때
// let _: () = iter;        // 일부러 틀려 에러 메시지로 타입 확인 (r02)

할당을 줄이는 요령 ★

// ① collect 를 남발하지 마세요 — 매번 힙 할당입니다
// ❌
let a: Vec<_> = it.map(f).collect();
let b: Vec<_> = a.iter().filter(g).collect();
// ✅ 한 번에
let b: Vec<_> = it.map(f).filter(g).collect();

// ② 크기를 알면 미리 잡기
let mut out = Vec::with_capacity(input.len());
out.extend(input.iter().map(f));
// collect 도 size_hint 를 보고 미리 잡습니다 (ExactSizeIterator 일 때) ★

// ③ 문자열은 to_string 대신 참조로
// ❌ .map(|u| u.name.clone())
// ✅ .map(|u| u.name.as_str())        // 수명이 허락하면

// ④ 기존 버퍼에 모으기
out.clear();
out.extend(it);                        // 할당 재사용 (o04)

// ⑤ 병렬로 — rayon 은 이터레이터와 같은 모양입니다 ★
use rayon::prelude::*;
let sum: i64 = data.par_iter().map(heavy).sum();     // ⚡ e05

// 측정 없이 최적화하지 마세요 (⚡ e01)

추상화가 사라지는 과정

let s: u64 = v.iter().map(|x| x * 2).filter(|x| x % 3 == 0).sum();

// ① 각 어댑터는 next() 를 구현한 구조체입니다
//    Sum<Filter<Map<slice::Iter>>>
// ② sum() 이 next() 를 반복 호출합니다
// ③ 컴파일러가 next() 를 전부 인라인합니다 (전부 제네릭 · 단형화 · r10)
// ④ 남은 것은 루프 하나 — 손으로 쓴 for 문과 동일한 기계어 ★

// 확인
//   cargo asm --lib my_fn
//   godbolt.org 에서 -O 로 비교

// ★ 오히려 더 빠를 수 있는 이유
//   · 슬라이스 이터레이터는 범위 검사가 없습니다 (v[i] 는 있음)
//   · 길이를 알아 LLVM 이 벡터화하기 쉽습니다 (⚡ e09)

// 벡터화가 걸렸는지 보려면 어셈블리에서 SIMD 명령을 찾으세요
//   x86: vpaddd · vmulps    ARM: fadd v0.4s

최적화가 깨지는 자리

// ① dyn 이 끼면 인라인이 안 됩니다
let f: Box<dyn Fn(&i32) -> i32> = Box::new(|x| x * 2);
v.iter().map(f)                        // 호출마다 간접 분기 (o06)

// ② 부동소수점 합은 순서를 못 바꿔 벡터화가 막힙니다
let s: f64 = v.iter().sum();           // 결합 법칙이 성립하지 않음 ★
// → 정확도를 포기해도 되면 청크로 나눠 부분합을 만드세요

// ③ 이터레이터를 컬렉션에 담으면 (Box<dyn Iterator>) 같은 문제

// ④ size_hint 가 부정확하면 collect 가 재할당합니다
//    filter 뒤에는 상한만 알 수 있습니다 (0..n)

// ⑤ 조기 종료가 있는 어댑터의 순서
v.iter().map(expensive).take(3);       // ✅ 3번만 계산 (지연 평가)
v.iter().filter(cheap).map(expensive); // ✅ 거른 뒤에 비싼 연산
v.iter().map(expensive).filter(cheap); // ❌ 전부 계산한 뒤 거름

// ★ 순서 규칙: 싸고 많이 거르는 것을 앞으로 ★

먼저 재세요 — 어디가 느린가

# ① 함수 단위로 어디가 오래 걸리나
python -m cProfile -s cumtime app.py | head -30

# ② 줄 단위로 (pip install line_profiler)
kernprof -l -v app.py            # @profile 데코레이터를 붙인 함수

# ③ 샘플링 프로파일러 — 운영 중인 프로세스에도 붙습니다 ★
pip install py-spy
py-spy top --pid 12345
py-spy record -o flame.svg --pid 12345

# ★ 판단 기준
#   · 전체의 5% 를 차지하는 함수를 100배 빠르게 해도 전체는 5% 만 빨라집니다
#   · 60% 이상을 차지하는 '핫스팟 하나'가 있을 때만 이득이 큽니다
#   · 그 함수가 순수 계산인가? (I/O 대기라면 Rust 로 바꿔도 그대로입니다)

Rust 이전에 시도할 것들 ★

★ Rust 가 실제로 유리한 경우
  · numpy 로 벡터화할 수 없는 '요소마다 다른 분기'가 있는 루프
  · 문자열·바이트 파싱 (numpy 가 못 다룸)
  · 트리·그래프 순회 같은 포인터 추적 작업
  · GIL 때문에 멀티스레드가 안 되는 CPU 작업 (y07)
  · 이미 Rust 로 된 좋은 크레이트가 있는 경우 (regex · serde · image)

★ Rust 가 불리한 경우
  · 병목이 I/O · 네트워크 대기
  · numpy 한 줄로 되는 행렬 연산 (이미 BLAS 가 C 로 최적화돼 있음)
  · 팀에 Rust 를 아는 사람이 나뿐인 경우 ★ (유지보수 비용)
  · 배포 대상이 다양한 플랫폼인데 CI 를 못 갖춘 경우 (🛠️ b08)

폴백을 남기는 구조 ★

# mypkg/__init__.py
import os

_USE_NATIVE = os.getenv("MYPKG_NATIVE", "1") != "0"

if _USE_NATIVE:
    try:
        from ._native import process          # Rust 확장
    except ImportError:                        # 휠이 없는 플랫폼
        from ._pure import process             # 순수 파이썬 폴백
else:
    from ._pure import process

__all__ = ["process"]

# tests/test_parity.py — 두 구현이 같은 결과를 내는지 ★
import pytest
from mypkg._pure import process as pure
from mypkg._native import process as native

@pytest.mark.parametrize("case", load_fixtures())
def test_parity(case):
    assert native(case) == pure(case)

경계를 좁게 잡습니다

★ 원칙 ① 경계를 넘는 '횟수'를 데이터 크기와 분리하라

  ❌ 나쁜 설계 — 요소마다 경계를 넘음
     for row in rows:            # 100만 번
         result.append(rust.process_one(row))

  ✅ 좋은 설계 — 한 번에 전부 넘김
     results = rust.process_batch(rows)      # 1번

  경계 통과 비용은 호출당 대략 수백 나노초입니다.
  100만 번이면 그것만으로 수백 밀리초 — 계산보다 큽니다. ★

★ 원칙 ② 좁고 안정된 인터페이스

  ❌ Rust 구조체 20개를 파이썬에 노출
  ✅ 함수 3개 · 클래스 1개 — 나머지는 안에 숨김
     내부를 자유롭게 바꿀 수 있고, 문서·스텁도 짧아집니다 (y10)

★ 원칙 ③ 측정하고 결정하라 — "빨라진 것 같다"는 근거가 아닙니다 (⚡ e01)
★ 원칙 ④ 되돌릴 수 있게 — 폴백 + parity 테스트
★ 원칙 ⑤ 안 쓰는 판단도 실력 — y01 의 표를 다시 보세요

손익분기점 계산

모델 (직접 재서 값을 채우세요 · ⚡ e01)

  파이썬 실행 시간      T_py
  Rust 실행 시간        T_rs        (보통 T_py / 10 ~ / 200)
  경계 통과 비용        C ≈ 0.1 ~ 1 μs / 호출
  변환 비용             V ∝ 데이터 크기 (제로카피면 ≈ 0 · y06)

  호출 n 번, 데이터 m 개일 때
    파이썬:  n · T_py(m)
    Rust  :  n · (C + V(m) + T_rs(m))

  → n 이 크고 m 이 작으면 C 가 지배합니다 (배치로 묶으세요)
  → m 이 크면 V 가 지배합니다 (제로카피가 필수 · y06)

실측 감각 (환경마다 다릅니다 — 반드시 직접 재세요)
  빈 함수 호출 왕복        약 0.1~0.3 μs
  리스트 100만 개 → Vec    수십 ms (복사 발생)
  numpy 배열 제로카피      약 0.001 ms (뷰만 만듦) ★

사람 비용도 계산에 넣으세요

★ 자주 잊는 비용들

  · CI 빌드 시간이 늘어납니다 (3 OS × 여러 아키텍처 · 🛠️ b08)
  · 기여자가 Rust 툴체인을 깔아야 합니다
  · 스택 트레이스가 파이썬에서 끊깁니다 (y12)
  · 새 파이썬 버전이 나오면 다시 빌드해야 합니다 (abi3 로 완화 · y11)
  · 팀의 다른 사람이 고칠 수 있는가 ★

★ 그럼에도 만들 가치가 있는 신호
  · 이 코드가 앞으로 몇 년 쓰일 것이 확실하다
  · 성능이 제품의 핵심 가치다 (응답 시간 · 처리량 SLA)
  · 파이썬으로는 물리적으로 불가능한 지점에 있다 (GIL · y07)
  · 이미 Rust 를 쓰는 다른 부분이 있다

★ 판단이 서지 않으면
  프로토타입을 하루 만들어 y03 까지 해 보고,
  실제 배수를 재서 결정하세요. 하루면 충분합니다.

처음부터 끝까지

# ① 준비 (한 번만)
pip install maturin            # 또는 uv tool install maturin

# ② 프로젝트 생성 — 뼈대를 전부 만들어 줍니다 ★
maturin new -b pyo3 fastmod
cd fastmod

# 만들어지는 것
#   Cargo.toml        Rust 설정
#   pyproject.toml    파이썬 패키지 설정
#   src/lib.rs        여기에 코드를 씁니다

# ③ 가상환경에 설치 (빌드 + install 을 한 번에)
python -m venv .venv && source .venv/bin/activate   # 윈도우: .venv\Scripts\activate
maturin develop --release       # ★ 이 한 줄이 전부입니다

# ④ 써 보기
python -c "import fastmod; print(fastmod.sum_squares(1000))"

코드 두 곳

// src/lib.rs
use pyo3::prelude::*;

/// 1..n 의 제곱합을 구합니다.
#[pyfunction]
fn sum_squares(n: u64) -> u64 {
    (1..=n).map(|x| x * x).sum()
}

#[pyfunction]
fn count_words(text: &str) -> usize {
    text.split_whitespace().count()
}

/// 파이썬 모듈 정의 — 이름이 Cargo.toml 의 lib.name 과 같아야 합니다 ★
#[pymodule]
fn fastmod(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(sum_squares, m)?)?;
    m.add_function(wrap_pyfunction!(count_words, m)?)?;
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
    Ok(())
}

# Cargo.toml
[package]
name = "fastmod"
version = "0.1.0"
edition = "2021"

[lib]
name = "fastmod"           # ★ #[pymodule] 함수 이름과 같아야 합니다
crate-type = ["cdylib"]    # ★ 동적 라이브러리로 (🔗 f02)

[dependencies]
pyo3 = { version = "0.23", features = ["extension-module"] }

매일 쓰는 명령

# 개발 중 — 빠른 반복
maturin develop                  # 디버그 빌드 (빠른 빌드 · 느린 실행)
maturin develop --release        # 릴리즈 (성능을 잴 땐 반드시 ★)
maturin develop -E test          # extras 도 함께 설치

# 테스트
cargo test                       # Rust 쪽 단위 테스트 (r11)
pytest                           # 파이썬 쪽 통합 테스트

# 배포용 빌드
maturin build --release          # target/wheels/*.whl
maturin publish                  # PyPI 로 (🛠️ b08)

# 확인
python -c "import fastmod; print(fastmod.__file__)"
pip show -f fastmod

첫 모듈에서 반드시 확인할 것

# tests/test_basic.py
import fastmod

def test_import():
    assert fastmod.__version__

def test_correctness():
    assert fastmod.sum_squares(3) == 14        # 1+4+9

def test_edge_cases():
    assert fastmod.sum_squares(0) == 0
    assert fastmod.count_words("") == 0
    assert fastmod.count_words("  여러   공백  ") == 2

def test_type_errors():
    import pytest
    with pytest.raises(TypeError):
        fastmod.sum_squares("문자열")           # ★ 타입 오류가 제대로 나는가

def test_no_crash_on_large():
    fastmod.count_words("x " * 1_000_000)      # ★ 큰 입력에 죽지 않는가

# 성능 비교 (같은 조건에서)
python -m timeit -s "import fastmod" "fastmod.sum_squares(1000000)"
python -m timeit "sum(x*x for x in range(1, 1000001))"

# ★ 반드시 --release 로 빌드한 뒤 재세요

import 가 하는 일

1. 파이썬이 fastmod/_native.cpython-312-x86_64-linux-gnu.so 를 찾습니다
2. dlopen() 으로 로드합니다
3. PyInit__native 심볼을 찾아 호출합니다 ★
4. 그 함수가 모듈 객체를 만들어 돌려줍니다

# 확인
python -c "import fastmod._native as m; print(m.__file__)"
nm -D fastmod/_native*.so | grep PyInit         # 리눅스
dumpbin /exports _native.pyd | findstr PyInit   # 윈도우

# ★ #[pymodule] 이 이 PyInit_ 함수를 생성합니다.
#   Cargo.toml 의 lib.name 과 함수 이름이 다르면
#   "dynamic module does not define module export function" 이 납니다 (y12)

파일 이름의 의미
  _native.cpython-312-x86_64-linux-gnu.so
          └ 파이썬 버전 ┘ └─ 플랫폼 ─┘
  → 이 파일은 CPython 3.12 · x86_64 리눅스 전용입니다
  → abi3 로 빌드하면 버전 부분이 abi3 가 되어 3.x 전체에서 씁니다 (y11)

Bound<'py, T> — PyO3 의 핵심 타입

use pyo3::prelude::*;

// PyO3 0.21+ 의 API — GIL 을 잡고 있다는 증거를 타입으로 표현합니다
#[pyfunction]
fn inspect(py: Python<'_>, obj: &Bound<'_, PyAny>) -> PyResult<String> {
    //      ^^^^^^^^^^^^ GIL 토큰       ^^^^^^^^^^^^^^^ GIL 에 묶인 참조
    let t = obj.get_type().name()?;
    Ok(format!("{t}"))
}

// 세 가지 형태
//   Python<'py>      GIL 을 잡고 있다는 증거 (토큰)
//   Bound<'py, T>    GIL 에 묶인 파이썬 객체 참조 ★ 대부분 이것
//   Py<T>            GIL 과 무관하게 보관 가능 (쓰려면 다시 GIL 필요)

// GIL 없이 보관하기 (구조체 필드 · 스레드 간 전달 · y09)
struct Holder { callback: Py<PyAny> }
impl Holder {
    fn call(&self, py: Python<'_>) -> PyResult<()> {
        self.callback.bind(py).call0()?;      // ★ GIL 을 다시 잡아 bind
        Ok(())
    }
}

// ★ 이 타입 설계 덕분에 "GIL 없이 파이썬 객체를 만졌다"가
//   컴파일 에러가 됩니다. C API 를 직접 쓸 때의 대표적 사고를 막습니다.

C++ 와 나란히 놓고 보기 ★

# C++ (pybind11 + scikit-build-core) 로 첫 모듈을 만들 때 필요한 것
  CMakeLists.txt            (약 20~40줄)
  pyproject.toml            (빌드 백엔드 · CMake 인자)
  src/main.cpp
  + 컴파일러 설치 (MSVC Build Tools / gcc / clang)
  + pybind11 를 어떻게 가져올지 결정 (FetchContent / vcpkg / pip)
  + 플랫폼별 플래그 처리
  + 빌드가 깨지면 CMake 에러 메시지를 해석해야 함

# Rust (PyO3 + maturin)
  Cargo.toml                (7줄)
  pyproject.toml            (5줄 · maturin new 가 만들어 줌)
  src/lib.rs
  + rustup 한 번

maturin 명령 전부

maturin new -b pyo3 이름       # 프로젝트 생성
maturin develop                # 현재 venv 에 설치 (개발용) ★
maturin develop --release      # 최적화 빌드로 설치
maturin build                  # wheel 만들기 → target/wheels/
maturin build --release --strip  # 배포용 (심볼 제거 · 🛠️ b10)
maturin sdist                  # 소스 배포판
maturin publish                # PyPI 업로드
maturin upload target/wheels/*.whl

# 옵션
--interpreter python3.11       # 특정 파이썬용으로
--features numpy               # cargo feature 켜기 (🛠️ b04)
--target aarch64-apple-darwin  # 크로스 (🛠️ b07)
--compatibility manylinux2014  # 리눅스 호환 태그
--zig                          # zig 로 링크해 크로스 빌드 ★

# uv 와 함께 (요즘 가장 빠른 조합)
uv venv && uv pip install maturin
uv run maturin develop --release

CI 에서 wheel 만들기 ★

# maturin 이 GitHub Actions 워크플로를 생성해 줍니다
maturin generate-ci github > .github/workflows/CI.yml

# 생성되는 것의 요약
#   · linux (x86_64 · aarch64 · musl) · windows · macos (x86_64 · arm64)
#   · 각 플랫폼에서 wheel 빌드 → 아티팩트 업로드
#   · 태그를 붙이면 PyPI 에 자동 배포
#
# ★ C++ 라면 cibuildwheel 설정 + 컨테이너 이미지 + 툴체인 준비가
#   필요한 자리인데, 여기서는 명령 한 줄로 생성됩니다 (🛠️ b08)

.github/workflows/CI.yml (핵심 부분)

  - uses: PyO3/maturin-action@v1
    with:
      target: ${{ matrix.target }}
      args: --release --out dist --find-interpreter
      manylinux: auto
      sccache: true              # 빌드 캐시 ★ (🛠️ b10)

  - name: publish
    if: startsWith(github.ref, 'refs/tags/')
    run: maturin upload --skip-existing dist/*

개발 편의 설정

# ① 빌드 캐시 — 재빌드가 크게 빨라집니다
cargo install sccache
export RUSTC_WRAPPER=sccache

# ② 링커 교체 (리눅스에서 링크가 느릴 때)
#   .cargo/config.toml
#   [target.x86_64-unknown-linux-gnu]
#   linker = "clang"
#   rustflags = ["-C", "link-arg=-fuse-ld=lld"]

# ③ 파일이 바뀌면 자동 재빌드
cargo install cargo-watch
cargo watch -s "maturin develop && pytest -x"

# ④ 에디터 — rust-analyzer 가 pyo3 매크로를 이해하게
#   .vscode/settings.json
#   "rust-analyzer.cargo.features": ["pyo3/extension-module"]

# ⑤ 개발 중 빌드 시간을 줄이는 프로파일 (🛠️ b06)
#   [profile.dev]
#   opt-level = 1          # 디버그인데 너무 느릴 때 절충

빌드 과정 뜯어보기

maturin develop -v

# 대략 이런 순서입니다
#  ① 현재 파이썬 인터프리터를 찾아 버전·ABI·플랫폼 태그를 알아냄
#  ② cargo rustc --crate-type cdylib -- (플랫폼별 링크 인자)
#     리눅스/맥: 파이썬 심볼을 '미해결'로 남깁니다 (extension-module)
#     윈도우: python3xx.lib 에 링크해야 합니다 ★ 플랫폼별 차이
#  ③ 결과 .so/.pyd 를 올바른 이름으로 복사
#     _native.cpython-312-x86_64-linux-gnu.so
#  ④ wheel 로 포장하고 pip install

# 왜 리눅스는 심볼을 안 채우나
#   확장 모듈은 이미 파이썬 프로세스 안에서 로드되므로
#   심볼이 런타임에 해결됩니다. 링크하면 오히려 심볼이 중복돼
#   미묘한 크래시가 납니다 (y12 의 대표 함정)

# 만들어진 wheel 안을 보기
unzip -l target/wheels/fastmod-0.1.0-cp312-*.whl

wheel 이름이 말해 주는 것

fastmod-0.1.0-cp312-cp312-manylinux_2_17_x86_64.whl
        │      │     │     │                  │
        │      │     │     │                  └ 아키텍처
        │      │     │     └ 플랫폼 태그 (glibc 2.17 이상)
        │      │     └ ABI 태그
        │      └ 파이썬 태그 (CPython 3.12 전용)
        └ 버전

fastmod-0.1.0-cp39-abi3-manylinux_2_17_x86_64.whl
                    ^^^^ ★ abi3 — 3.9 이상 모든 CPython 에서 동작 (y11)

★ 태그가 안 맞으면 pip 가 설치를 거부합니다
   "is not a supported wheel on this platform"
   → 그 플랫폼용 wheel 이 없는 것입니다 (sdist 로 폴백되어 컴파일 시도)

# 내 환경의 태그 확인
python -c "from packaging.tags import sys_tags; print(next(iter(sys_tags())))"

# manylinux 검사
pip install auditwheel
auditwheel show dist/*.whl        # 어떤 라이브러리에 의존하는지 ★

기본 대응표 ★

use pyo3::prelude::*;
use std::collections::HashMap;

#[pyfunction]
fn stats(nums: Vec<f64>) -> (f64, f64) {          // list[float] → Vec (복사)
    let n = nums.len() as f64;
    let mean = nums.iter().sum::<f64>() / n;
    let var = nums.iter().map(|x| (x - mean).powi(2)).sum::<f64>() / n;
    (mean, var.sqrt())                            // → tuple
}

#[pyfunction]
fn count(text: &str) -> HashMap<String, usize> {  // str → &str (복사 없음) ★
    let mut m = HashMap::new();
    for w in text.split_whitespace() {
        *m.entry(w.to_string()).or_insert(0) += 1;
    }
    m                                             // → dict
}

복사를 피하는 형태

// ❌ 리스트를 통째로 복사 — 100만 개면 눈에 띕니다
#[pyfunction]
fn sum_slow(v: Vec<f64>) -> f64 { v.iter().sum() }

// ✅ ① numpy 배열로 받기 — 복사 0 (y06)
use numpy::PyReadonlyArray1;
#[pyfunction]
fn sum_fast(a: PyReadonlyArray1<f64>) -> f64 {
    a.as_slice().unwrap().iter().sum()
}

// ✅ ② bytes 로 받기 — 복사 0
#[pyfunction]
fn checksum(data: &[u8]) -> u32 {
    data.iter().fold(0u32, |a, b| a.wrapping_add(*b as u32))
}

// ✅ ③ 시퀀스를 순회만 (전체 Vec 을 만들지 않음)
use pyo3::types::PyList;
#[pyfunction]
fn sum_iter(v: &Bound<'_, PyList>) -> PyResult<f64> {
    let mut s = 0.0;
    for item in v.iter() { s += item.extract::<f64>()?; }
    Ok(s)
}
// ★ 다만 요소마다 파이썬 객체를 만지므로 numpy 만큼 빠르지는 않습니다.
//   큰 수치 데이터는 반드시 numpy 로 받으세요 (y06)

호출 횟수를 줄이는 것이 먼저 ★

# ❌ 요소마다 경계를 넘음 — 100만 번 × 0.2μs = 0.2초 (계산 전)
results = [fastmod.score(row) for row in rows]

# ✅ 한 번에 넘김
results = fastmod.score_batch(rows)

# ✅✅ numpy 로 넘김 (복사조차 없음 · y06)
import numpy as np
arr = np.asarray(rows, dtype=np.float64)
results = fastmod.score_array(arr)

// 배치 API 는 이렇게 씁니다
#[pyfunction]
fn score_batch(rows: Vec<Vec<f64>>) -> Vec<f64> {
    rows.iter().map(|r| score_one(r)).collect()
}

// 병렬까지 (y07)
use rayon::prelude::*;
#[pyfunction]
fn score_batch_par(py: Python<'_>, rows: Vec<Vec<f64>>) -> Vec<f64> {
    py.allow_threads(|| rows.par_iter().map(|r| score_one(r)).collect())
}

문자열을 다룰 때의 주의

// str → &str 은 복사가 없지만, 조건이 있습니다
#[pyfunction]
fn f(s: &str) { }
// ★ CPython 이 UTF-8 캐시를 갖고 있으면 그대로 빌려 옵니다.
//   없으면 내부적으로 UTF-8 로 변환합니다 (첫 호출에 한 번)

// 소유가 필요하면 명시적으로
#[pyfunction]
fn store(s: String) { }                 // 복사가 일어납니다

// 대량 문자열은 bytes 로 주고받는 것이 빠릅니다
#[pyfunction]
fn parse_lines(data: &[u8]) -> PyResult<Vec<String>> {
    let text = std::str::from_utf8(data)?;      // 검증 1회
    Ok(text.lines().map(String::from).collect())
}
// 파이썬: fastmod.parse_lines(open("f.txt","rb").read())

// ❗ 반환 문자열이 많으면 그것도 비용입니다
//   → 인덱스·오프셋만 돌려주고 파이썬이 슬라이싱하게 하는 설계도 있습니다
#[pyfunction]
fn find_spans(text: &str, pat: &str) -> Vec<(usize, usize)> { }

list → Vec 이 하는 일

파이썬 list[float] 100만 개의 실제 모습
  · PyListObject 하나 (포인터 배열 8MB)
  · PyFloatObject 100만 개 (각 24바이트 · 힙에 흩어져 있음) ★

Vec<f64> 로 변환하면
  ① 리스트 길이를 읽어 Vec::with_capacity
  ② 포인터를 하나씩 따라가며 (캐시 미스 ★)
  ③ PyFloat_AsDouble 로 f64 추출
  ④ Vec 에 push

→ 100만 번의 포인터 추적 + 타입 검사입니다.
  numpy 배열이라면 ①만 하고 끝납니다 (연속된 8MB 를 그대로 봄 · y06)

측정 방법 (직접 재 보세요)
  python -m timeit -s "import fastmod, random;
      d=[random.random() for _ in range(1_000_000)]" "fastmod.sum_slow(d)"
  python -m timeit -s "import fastmod, numpy as np;
      a=np.random.random(1_000_000)" "fastmod.sum_fast(a)"

extract 의 동작과 오류

// extract 는 '파이썬 객체 → Rust 타입' 시도입니다
let n: i64 = obj.extract()?;               // 실패하면 TypeError

// 관대한 변환에 주의하세요
// bool 은 int 로도 추출됩니다 (파이썬에서 True == 1)
// float 자리에 int 를 주면 통과합니다
// → 엄격하게 검사하려면 타입을 먼저 확인하세요
use pyo3::types::PyFloat;
if !obj.is_instance_of::<PyFloat>() {
    return Err(PyTypeError::new_err("float 이어야 합니다"));
}

// 큰 정수 오버플로
let n: u8 = obj.extract()?;                // 300 을 주면 OverflowError ★

// 성능: extract 는 매번 타입 검사를 합니다
// 루프 안에서 수백만 번 부르면 그것만으로 비용이 됩니다
// → 배치 · numpy 로 우회하세요

// GIL 없이 보관하려면 소유 타입으로 미리 변환
let owned: Vec<f64> = obj.extract()?;      // GIL 이 필요 없는 순수 Rust 값
py.allow_threads(|| heavy(&owned));        // ★ 이제 GIL 을 놓을 수 있습니다 (y07)

기본 형태

use pyo3::prelude::*;

#[pyclass]
struct Counter {
    #[pyo3(get)]                 // 읽기 전용 속성
    total: u64,
    #[pyo3(get, set)]            // 읽고 쓰기
    step: u64,
    history: Vec<u64>,           // 표시 안 함 (내부용)
}

#[pymethods]
impl Counter {
    #[new]                       // __init__
    #[pyo3(signature = (step = 1))]
    fn new(step: u64) -> Self {
        Counter { total: 0, step, history: Vec::new() }
    }

    fn increment(&mut self) -> u64 {
        self.total += self.step;
        self.history.push(self.total);
        self.total
    }

    fn reset(&mut self) { self.total = 0; self.history.clear(); }

    #[getter]                    // 계산되는 속성
    fn count(&self) -> usize { self.history.len() }

    fn __repr__(&self) -> String { format!("Counter(total={})", self.total) }
    fn __len__(&self) -> usize { self.history.len() }
}

// 모듈에 등록
#[pymodule]
fn fastmod(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<Counter>()?;
    Ok(())
}

파이썬에서 쓰기

from fastmod import Counter

c = Counter(step=5)
c.increment()          # 5
c.increment()          # 10
print(c.total)         # 10   (get)
c.step = 10            # (set)
print(c.count)         # 2    (getter)
print(len(c))          # 2    (__len__)
print(c)               # Counter(total=10)  (__repr__)

# c.total = 99         # ❌ AttributeError — get 만 있으므로

// 자주 쓰는 던더 메서드
#[pymethods]
impl Counter {
    fn __str__(&self) -> String { }
    fn __eq__(&self, other: &Self) -> bool { self.total == other.total }
    fn __hash__(&self) -> u64 { self.total }
    fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> { slf }
    fn __next__(&mut self) -> Option<u64> { }
    fn __getitem__(&self, i: usize) -> PyResult<u64> { }
    fn __enter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> { slf }   // with 문
    fn __exit__(&mut self, _t: &Bound<'_, PyAny>,
                _v: &Bound<'_, PyAny>, _tb: &Bound<'_, PyAny>) { self.close(); }
}

// 클래스 메서드 · 정적 메서드
#[pymethods]
impl Counter {
    #[staticmethod]
    fn version() -> &'static str { env!("CARGO_PKG_VERSION") }
    #[classmethod]
    fn from_list(_cls: &Bound<'_, PyType>, v: Vec<u64>) -> Self { }
}

빌림 규칙이 런타임으로 옮겨 옵니다 ★

// #[pyclass] 는 내부적으로 RefCell 같은 검사를 씁니다 (🔐 o10)
// → 빌림 충돌이 '컴파일 에러'가 아니라 '파이썬 예외'가 됩니다

#[pymethods]
impl Node {
    fn add_child(&mut self, other: PyRef<'_, Node>) { }
}
// 파이썬에서 n.add_child(n) 을 하면
//   RuntimeError: Already borrowed
// ★ 자기 자신을 넘기는 경우가 실제로 자주 생깁니다

// 방어 방법
//   · 가능하면 #[pyclass(frozen)] 으로 두고 &self 만 쓰기
//   · 내부 상태를 Mutex/RwLock 으로 감싸기
use std::sync::Mutex;
#[pyclass(frozen)]
struct Shared { inner: Mutex<State> }

#[pymethods]
impl Shared {
    fn update(&self, v: u64) {          // &self 라 충돌이 없습니다
        self.inner.lock().unwrap().value = v;
    }
}

// PyRef / PyRefMut — 다른 인스턴스를 빌릴 때
fn merge(&mut self, other: PyRef<'_, Self>) { self.total += other.total; }

복사 · 피클 · 컨텍스트 매니저

use pyo3::types::PyBytes;

#[pymethods]
impl Model {
    // copy.deepcopy 지원
    fn __copy__(&self) -> Self { self.clone() }
    fn __deepcopy__(&self, _memo: &Bound<'_, PyAny>) -> Self { self.clone() }

    // pickle 지원 — 멀티프로세싱에 필요합니다 ★
    fn __getstate__(&self, py: Python<'_>) -> PyResult<Py<PyBytes>> {
        let bytes = bincode::serialize(&self.data).unwrap();
        Ok(PyBytes::new(py, &bytes).unbind())
    }
    fn __setstate__(&mut self, state: &Bound<'_, PyBytes>) -> PyResult<()> {
        self.data = bincode::deserialize(state.as_bytes()).unwrap();
        Ok(())
    }
    #[staticmethod]
    fn __getnewargs__() -> (u32,) { (0,) }
}

// ★ 피클을 지원하지 않으면 multiprocessing 으로 넘길 때
//   "cannot pickle 'Model' object" 가 납니다.
//   확장을 쓰는 코드가 병렬 처리를 하면 반드시 만나는 문제입니다 (y12)

메모리 배치

파이썬 객체 헤더 + PyO3 셀 + 내 구조체가 한 덩어리로 힙에 놓입니다

  ┌──────────────┬───────────┬──────────────┐
  │ PyObject_HEAD│ borrow    │ Counter      │
  │ (refcnt·type)│ flag      │ (내 필드들)   │
  └──────────────┴───────────┴──────────────┘

★ 그래서 Rust 구조체를 '파이썬 객체 안에' 두는 것이고,
  Rust 쪽에서 &mut 를 얻으려면 borrow flag 를 확인해야 합니다.

# 확인
python -c "
import fastmod, sys
c = fastmod.Counter()
print(sys.getsizeof(c), sys.getrefcount(c))"

# 매크로가 생성한 코드 보기
cargo install cargo-expand
cargo expand --lib > expanded.rs        # ★ #[pyclass] 가 만든 impl 전부

성능 비교 — 함수 vs 클래스

// 클래스 메서드 호출의 추가 비용
//   ① 파이썬 메서드 조회 (타입 dict)
//   ② self 를 Rust 참조로 변환 (borrow flag 확인)
//   ③ 인자 변환
// → 함수 호출보다 조금 더 비쌉니다 (보통 수십 ns 차이)

// ★ 그래서 판단 기준은 성능이 아니라 '상태가 필요한가' 입니다.
//   상태 재사용의 이득(정규식 컴파일 등)이 호출 비용보다 훨씬 큽니다.

// 인스턴스를 Rust 쪽에서 보관하기
#[pyfunction]
fn register(obj: Py<Counter>) -> PyResult<()> {
    REGISTRY.lock().unwrap().push(obj);       // GIL 없이 보관 가능 (y02)
    Ok(())
}

// 순환 참조 주의 — 파이썬 GC 와 연동하려면
#[pyclass]
struct Holder { obj: Option<Py<PyAny>> }
#[pymethods]
impl Holder {
    fn __traverse__(&self, visit: PyVisit<'_>) -> Result<(), PyTraverseError> {
        if let Some(o) = &self.obj { visit.call(o)?; }
        Ok(())
    }
    fn __clear__(&mut self) { self.obj = None; }
}
// ★ 파이썬 객체를 필드로 들고 있으면 이걸 구현해야 GC 가 순환을 끊습니다

읽기 — PyReadonlyArray

# Cargo.toml
[dependencies]
pyo3 = { version = "0.23", features = ["extension-module"] }
numpy = "0.23"

use numpy::{PyReadonlyArray1, PyReadonlyArray2};
use pyo3::prelude::*;

#[pyfunction]
fn mean(a: PyReadonlyArray1<f64>) -> f64 {
    let s = a.as_slice().unwrap();        // ★ &[f64] — 복사 없음
    s.iter().sum::<f64>() / s.len() as f64
}

// 2차원
#[pyfunction]
fn row_sums(a: PyReadonlyArray2<f64>) -> Vec<f64> {
    let arr = a.as_array();               // ndarray::ArrayView2
    arr.rows().into_iter().map(|r| r.sum()).collect()
}

// as_slice() 가 실패하는 경우 ★
//   · 배열이 연속(C-contiguous)이 아닐 때 (a[::2] 같은 뷰)
//   → 파이썬 쪽에서 np.ascontiguousarray() 를 부르게 하거나
//   → as_array() 로 ndarray 뷰를 쓰세요 (스트라이드를 처리합니다)

import numpy as np, fastmod
a = np.random.random(10_000_000)
fastmod.mean(a)          # 복사 없음 — 배열 크기와 무관하게 즉시 시작

쓰기 · 새 배열 만들기

use numpy::{PyArray1, PyArrayMethods, PyReadwriteArray1, IntoPyArray};

// 제자리 수정 (in-place) — 할당조차 없습니다 ★
#[pyfunction]
fn scale_inplace(mut a: PyReadwriteArray1<f64>, k: f64) {
    let s = a.as_slice_mut().unwrap();
    for x in s.iter_mut() { *x *= k; }
}

// 새 배열 반환
#[pyfunction]
fn doubled<'py>(py: Python<'py>, a: PyReadonlyArray1<f64>)
    -> Bound<'py, PyArray1<f64>>
{
    let v: Vec<f64> = a.as_slice().unwrap().iter().map(|x| x * 2.0).collect();
    v.into_pyarray(py)                   // Vec 을 numpy 배열로 (소유권 이전)
}

// 출력 버퍼를 받는 형태 — 가장 빠릅니다 (🔐 o04 의 패턴)
#[pyfunction]
fn transform(a: PyReadonlyArray1<f64>, mut out: PyReadwriteArray1<f64>)
    -> PyResult<()>
{
    let src = a.as_slice()?;
    let dst = out.as_slice_mut()?;
    if src.len() != dst.len() {
        return Err(pyo3::exceptions::PyValueError::new_err("길이가 다릅니다"));
    }
    for (d, s) in dst.iter_mut().zip(src) { *d = s.sqrt(); }
    Ok(())
}

정직한 기대치 ★

★ Rust 가 numpy 를 못 이기는 경우
  · a + b, a * b 같은 원소별 연산     → numpy 도 이미 C · SIMD
  · 행렬 곱 (a @ b)                   → BLAS 가 수십 년 최적화됨
  · np.sum, np.mean                   → 이미 벡터화됨
  → 이런 건 Rust 로 옮겨도 같거나 느립니다. 옮기지 마세요.

★ Rust 가 크게 이기는 경우
  · 요소마다 분기가 다른 루프
      for x in a: if cond(x): ... else: ...     ← 파이썬 루프면 100배
  · 임시 배열이 여러 개 생기는 식
      (a*b + c*d) / (e+f)   → numpy 는 중간 배열을 5개 만듭니다
      Rust 는 한 번의 순회로 끝냅니다 (메모리 대역폭 이득) ★
  · 문자열·바이트 파싱 (numpy 가 잘 못하는 영역)
  · 조기 종료가 있는 탐색
  · 상태를 이어 가는 순차 처리 (누적·필터·상태 머신)

★ 실측 방법
  같은 데이터로 numpy 버전과 Rust 버전을 나란히 재세요 (⚡ e01)
  "몇 배"는 데이터 크기·CPU·메모리 대역폭에 따라 크게 달라집니다.

퓨전 — 임시 배열을 없애기

# numpy — 중간 배열이 여러 개 생깁니다
result = np.sqrt(a**2 + b**2) / (c + 1e-9)
#        ↑        ↑    ↑   ↑     ↑
#      임시4    임시1 임시2 임시3  임시5    (각각 8MB 씩이면 40MB 순회)

// Rust — 한 번의 순회, 임시 배열 0
#[pyfunction]
fn fused<'py>(py: Python<'py>,
              a: PyReadonlyArray1<f64>,
              b: PyReadonlyArray1<f64>,
              c: PyReadonlyArray1<f64>) -> PyResult<Bound<'py, PyArray1<f64>>>
{
    let (a, b, c) = (a.as_slice()?, b.as_slice()?, c.as_slice()?);
    let out: Vec<f64> = (0..a.len())
        .map(|i| (a[i]*a[i] + b[i]*b[i]).sqrt() / (c[i] + 1e-9))
        .collect();
    Ok(out.into_pyarray(py))
}
// ★ 메모리 대역폭이 병목인 큰 배열에서 차이가 큽니다.
//   numba 의 @njit 도 같은 원리로 빨라집니다 — 비교해 보고 고르세요 (y01)

제로카피가 성립하는 조건

numpy 배열이 Rust 슬라이스가 되는 조건
  ① dtype 이 정확히 일치 (f64 ↔ np.float64)
  ② 연속 메모리 (C-contiguous) — as_slice() 를 쓸 때
  ③ 정렬(alignment)이 맞음
  ④ GIL 을 잡고 있는 동안만 유효 ★

★ ④ 가 중요합니다
  파이썬이 그 배열을 GC 하면 슬라이스는 해제된 메모리를 가리킵니다.
  PyReadonlyArray 는 내부적으로 참조를 유지해 이를 막습니다.
  → 그래서 슬라이스를 구조체에 저장해 오래 들고 있으면 안 됩니다.

  allow_threads(y07) 안에서 쓰려면
  · PyReadonlyArray 를 밖에서 만들고
  · as_slice() 로 얻은 &[f64] 만 클로저에 넘깁니다
  · 파이썬 쪽이 그 사이에 배열을 바꾸지 않는다는 전제가 필요합니다 ★

경쟁 조건을 만들지 않기

// ❗ 위험한 패턴 — GIL 을 놓은 채 파이썬이 만질 수 있는 메모리를 씀
#[pyfunction]
fn danger(py: Python<'_>, mut a: PyReadwriteArray1<f64>) {
    let s = a.as_slice_mut().unwrap();
    py.allow_threads(|| {              // ★ 다른 파이썬 스레드가 a 를 읽을 수 있음
        for x in s.iter_mut() { *x *= 2.0; }
    });
}
// PyReadwriteArray 는 배열을 '쓰기 잠금'하므로 numpy 레벨에서는 보호되지만,
// 같은 메모리를 보는 다른 뷰(a[::1] 등)까지 막지는 못합니다.

// ✅ 안전한 관례
//   · 입력은 readonly, 출력은 새 배열 또는 전용 out 배열
//   · 문서에 "처리 중 입력 배열을 수정하지 마세요" 를 명시
//   · 확실히 하려면 Vec 으로 복사한 뒤 allow_threads (복사 비용 vs 안전)

// 검증
//   · Miri 는 FFI 경계를 못 봅니다 (🔬 d07)
//   · 대신 파이썬 쪽에서 스레드 스트레스 테스트를 쓰세요
//   · ASAN 빌드: RUSTFLAGS="-Zsanitizer=address" (nightly)

allow_threads — GIL 놓기

use pyo3::prelude::*;

#[pyfunction]
fn heavy(py: Python<'_>, data: Vec<f64>) -> f64 {
    py.allow_threads(|| {            // ★ 이 안에서는 GIL 을 놓습니다
        data.iter().map(|x| expensive(*x)).sum()
    })
    // 클로저 안에서는 파이썬 객체를 만질 수 없습니다 (컴파일러가 막습니다)
}

// ★ 규칙: 클로저에 넘기는 것은 '순수 Rust 값' 이어야 합니다
//   Vec<f64>  ✅    &[u8]  ✅    Bound<PyAny>  ❌ (컴파일 에러)

// 언제 놓아야 하나
//   · 계산이 밀리초 이상 걸릴 때 ★
//   · I/O 를 할 때 (파일·네트워크)
//   · 놓고 잡는 비용이 있으니 마이크로초 단위 작업엔 오히려 손해

# 효과 확인 — 파이썬 스레드 4개로 동시에 부르기
from concurrent.futures import ThreadPoolExecutor
import fastmod, time

t = time.perf_counter()
with ThreadPoolExecutor(max_workers=4) as ex:
    list(ex.map(fastmod.heavy, [data]*4))
print(time.perf_counter() - t)
# GIL 을 놓으면 ≈ 1배 시간, 안 놓으면 ≈ 4배 시간 ★

rayon — 한 줄 병렬화 ★

[dependencies]
rayon = "1"

use rayon::prelude::*;

#[pyfunction]
fn score_all(py: Python<'_>, rows: Vec<Vec<f64>>) -> Vec<f64> {
    py.allow_threads(|| {
        rows.par_iter()              // ★ iter() → par_iter() 여섯 글자
            .map(|r| score_one(r))
            .collect()
    })
}

// numpy 배열을 병렬로 (y06 과 조합)
use numpy::{PyReadonlyArray1, PyArray1, IntoPyArray};
#[pyfunction]
fn transform<'py>(py: Python<'py>, a: PyReadonlyArray1<f64>)
    -> PyResult<Bound<'py, PyArray1<f64>>>
{
    let src = a.as_slice()?;
    let out: Vec<f64> = py.allow_threads(|| {
        src.par_iter().map(|x| heavy_fn(*x)).collect()
    });
    Ok(out.into_pyarray(py))
}

// 제자리 병렬 수정
data.par_chunks_mut(1024).for_each(|c| process(c));

// 스레드 수 제한 (⚡ e05)
rayon::ThreadPoolBuilder::new().num_threads(4).build_global().unwrap();

컴파일러가 막아 주는 것 ★

// allow_threads 의 클로저는 Send + 'static 을 요구합니다 (🔐 o03)
// → 파이썬 객체(Bound<PyAny>)는 Send 가 아니므로 컴파일 에러가 납니다

#[pyfunction]
fn wrong(py: Python<'_>, obj: &Bound<'_, PyAny>) {
    // py.allow_threads(|| { obj.call0(); });
    //   error: `Bound<'_, PyAny>` cannot be sent between threads safely ★
}

// ✅ GIL 밖에서 쓸 값만 미리 뽑습니다
#[pyfunction]
fn right(py: Python<'_>, obj: &Bound<'_, PyAny>) -> PyResult<f64> {
    let data: Vec<f64> = obj.extract()?;         // GIL 잡은 채 변환
    Ok(py.allow_threads(|| heavy(&data)))        // 순수 Rust 값만 넘김
}

// rayon 안에서 데이터 경쟁도 컴파일러가 막습니다 (⚡ e06)
//   par_iter().map() 안에서 공유 가변 상태를 만지면 빌드가 안 됩니다
//   → 결과를 collect 하거나 원자 타입·Mutex 를 쓰게 됩니다

// ★ 이것이 C++ 확장과 갈리는 실무 지점입니다.
//   C++ 에서 GIL 을 놓고 파이썬 객체를 만지면 '가끔' 크래시합니다.
//   Rust 에서는 그 코드가 컴파일되지 않습니다.

진행률과 취소 지원

use std::sync::atomic::{AtomicUsize, AtomicBool, Ordering};
use std::sync::Arc;

#[pyclass]
struct Job {
    done: Arc<AtomicUsize>,
    cancel: Arc<AtomicBool>,
}

#[pymethods]
impl Job {
    fn run(&self, py: Python<'_>, data: Vec<f64>) -> PyResult<Vec<f64>> {
        let (done, cancel) = (self.done.clone(), self.cancel.clone());
        let out = py.allow_threads(move || {
            data.par_iter().map(|x| {
                done.fetch_add(1, Ordering::Relaxed);
                f(*x)
            }).collect::<Vec<_>>()
        });
        Ok(out)
    }
    #[getter] fn progress(&self) -> usize { self.done.load(Ordering::Relaxed) }
    fn cancel(&self) { self.cancel.store(true, Ordering::Relaxed); }
}

// ❗ Ctrl+C 처리 — GIL 을 놓은 동안 파이썬은 시그널을 처리하지 못합니다
//   긴 작업이라면 주기적으로 체크하세요
py.check_signals()?;                    // KeyboardInterrupt 를 전파 ★

allow_threads 가 하는 일

py.allow_threads(f) 는 대략 이렇습니다

  PyThreadState *_save = PyEval_SaveThread();   // GIL 해제 + 상태 저장
  f();                                          // Rust 코드 실행
  PyEval_RestoreThread(_save);                  // GIL 재획득

★ 비용
  해제·재획득이 각각 수백 나노초 수준입니다.
  경합이 심하면 재획득에 훨씬 오래 걸릴 수 있습니다.
  → 마이크로초 단위 작업을 감쌀 때는 순이익이 마이너스입니다.

★ 클로저가 panic 하면?
  PyO3 가 잡아서 GIL 을 복구한 뒤 파이썬 예외로 바꿉니다 (y08).
  다만 panic = "abort" 프로파일이면 프로세스가 죽습니다 (y03 주의).

★ 재진입 금지
  allow_threads 안에서 파이썬 API 를 부르면 UB 입니다.
  PyO3 의 타입 시스템이 이를 막지만, unsafe 로 우회하면 뚫립니다.

free-threaded CPython (3.13+)

파이썬 3.13 부터 GIL 없는 빌드가 실험적으로 제공됩니다 (PEP 703).
  python3.13t   ← 't' 가 free-threaded 빌드

★ 확장 모듈 입장에서 달라지는 것
  · 여러 스레드가 '동시에' 내 함수에 들어올 수 있습니다
  · #[pyclass] 인스턴스를 GIL 이 더는 보호하지 않습니다 ★
  · 모듈이 지원한다고 선언해야 합니다

# PyO3 에서 (버전에 따라 방법이 다릅니다 — 문서 확인)
#[pymodule(gil_used = false)]
fn fastmod(m: &Bound<'_, PyModule>) -> PyResult<()> { }

★ 대비하는 법 (지금부터 해 두면 좋은 것)
  · #[pyclass(frozen)] + Mutex/Atomic 으로 상태를 보호 (y05)
  · 전역 가변 상태를 만들지 않기 (r02 의 OnceLock 패턴)
  · 스레드 스트레스 테스트를 CI 에 두기

★ 아이러니
  GIL 이 사라지면 "Rust 로 GIL 을 놓는" 이점 하나는 줄어듭니다.
  하지만 '데이터 경쟁을 컴파일러가 막는' 이점은 오히려 더 중요해집니다 (⚡ e06).

가장 간단한 형태

use pyo3::prelude::*;
use pyo3::exceptions::{PyValueError, PyIndexError, PyTypeError, PyIOError};

#[pyfunction]
fn divide(a: f64, b: f64) -> PyResult<f64> {
    if b == 0.0 {
        return Err(PyValueError::new_err("0 으로 나눌 수 없습니다"));
    }
    Ok(a / b)
}

// 표준 에러는 자동으로 변환됩니다 ★
#[pyfunction]
fn read(path: &str) -> PyResult<String> {
    Ok(std::fs::read_to_string(path)?)     // io::Error → OSError 자동
}

#[pyfunction]
fn parse(s: &str) -> PyResult<i64> {
    Ok(s.parse()?)                         // ParseIntError → ValueError 자동
}

// 자동 변환되는 것들
//   std::io::Error        → OSError (세부는 ErrorKind 에 따라)
//   ParseIntError         → ValueError
//   Utf8Error             → UnicodeDecodeError
//   TryFromIntError       → OverflowError
//   std::fmt::Error       → RuntimeError

내 에러 타입을 연결하기 ★

use thiserror::Error;                      // (🔐 o09)

#[derive(Error, Debug)]
pub enum CoreError {
    #[error("입력이 비었습니다")]                Empty,
    #[error("길이 초과: {got} > {max}")]         TooLong { got: usize, max: usize },
    #[error("잘못된 형식: {0}")]                 BadFormat(String),
    #[error("파일 오류")]                       Io(#[from] std::io::Error),
}

// ★ From 을 구현하면 ? 하나로 변환됩니다
impl From<CoreError> for PyErr {
    fn from(e: CoreError) -> PyErr {
        match e {
            CoreError::Empty          => PyValueError::new_err(e.to_string()),
            CoreError::TooLong { .. } => PyOverflowError::new_err(e.to_string()),
            CoreError::BadFormat(_)   => PyValueError::new_err(e.to_string()),
            CoreError::Io(io)         => PyIOError::new_err(io.to_string()),
        }
    }
}

#[pyfunction]
fn process(text: &str) -> PyResult<String> {
    Ok(core_process(text)?)                // CoreError → PyErr 자동
}

try:
    fastmod.process("")
except ValueError as e:        # ★ 종류별로 잡힙니다
    print(e)                   # 입력이 비었습니다

패닉은 자동으로 잡힙니다 — 단, 조건이 있습니다 ★

#[pyfunction]
fn boom() {
    panic!("무언가 잘못됨");
}
// 파이썬에서:
//   pyo3_runtime.PanicException: 무언가 잘못됨
// → PyO3 가 패닉을 잡아 예외로 바꿔 줍니다

// ❗ 단, 두 경우엔 프로세스가 그대로 죽습니다
//   ① Cargo.toml 에 panic = "abort" 가 있을 때 (y03)
//   ② allow_threads 밖의 다른 스레드에서 패닉했을 때

// ★ 실무 원칙: 패닉에 의존하지 마세요
// ❌
#[pyfunction]
fn get(v: Vec<i64>, i: usize) -> i64 { v[i] }      // 범위 밖이면 패닉

// ✅
#[pyfunction]
fn get(v: Vec<i64>, i: usize) -> PyResult<i64> {
    v.get(i).copied()
        .ok_or_else(|| PyIndexError::new_err(format!("범위 밖: {i}")))
}

// unwrap 을 남긴 채 배포하지 마세요
//   cargo clippy -- -W clippy::unwrap_used -W clippy::expect_used

에러 메시지 품질 체크리스트

□ 무엇을 하려다 실패했는가
    ❌ "실패"
    ✅ "설정 파일 파싱 실패: /etc/app.toml"

□ 어떤 값이 문제였는가
    ❌ "잘못된 입력"
    ✅ "잘못된 포트: 99999 (허용 1~65535)"

□ 어떻게 고치는가
    ✅ "float64 배열이어야 합니다. np.asarray(a, dtype=np.float64) 를 쓰세요"

□ 예외 타입이 적절한가
    타입이 틀림      → TypeError
    값이 범위 밖     → ValueError
    인덱스 밖        → IndexError
    키 없음          → KeyError
    파일·OS          → OSError
    구현 안 됨       → NotImplementedError

□ 민감 정보가 없는가 (토큰·비밀번호가 메시지에 섞이는 사고가 흔합니다)

□ 파이썬 관례를 따르는가
    메시지는 대문자로 시작하지 않고, 마침표를 붙이지 않는 것이 관례입니다
    (한글이면 "~합니다" 로 통일하는 편이 읽기 좋습니다)

지연 생성과 비용

// PyErr 는 '아직 파이썬 객체가 아닌 상태' 로 만들어집니다 (지연 생성)
let e = PyValueError::new_err("메시지");     // 아직 예외 객체를 안 만듦
// → 실제 객체는 파이썬으로 넘어갈 때 만들어집니다
//   에러 경로가 잦아도 비용이 크지 않은 이유입니다 ★

// 이미 발생한 에러 가져오기 (C API 를 직접 쓸 때)
if let Some(e) = PyErr::take(py) { }

// 예외 정보 꺼내기
let e: PyErr = ...;
e.get_type(py);              // 예외 클래스
e.value(py);                 // 예외 인스턴스
e.traceback(py);             // 트레이스백
e.is_instance_of::<PyValueError>(py);

// 출력 후 지우기 (콜백 안에서 에러를 삼켜야 할 때)
e.print(py);                 // stderr 로 출력
e.restore(py);               // 파이썬 에러 상태로 되돌리기

// ★ 성능 팁: 에러 메시지를 format! 으로 매번 만들면
//   성공 경로에서도 비용이 듭니다. 지연 생성하세요
.ok_or_else(|| PyValueError::new_err(format!("…{i}")))   // ✅ 실패할 때만
.ok_or(PyValueError::new_err(format!("…{i}")))           // ❌ 항상 만듦

에러 처리 전체 그림

내부 로직 (순수 Rust)
    ↓  thiserror 로 구체적인 에러 타입 (🔐 o09)
CoreError
    ↓  impl From<CoreError> for PyErr    ← ★ 경계에서 딱 한 번 변환
PyErr
    ↓  PyO3 가 파이썬으로 던짐
ValueError / ParseError / …
    ↓
파이썬 사용자가 종류별로 except

★ 이 구조의 이점
  · 내부 로직은 파이썬을 전혀 모릅니다 → 순수 Rust 테스트 가능 (r11)
  · 같은 로직을 Node 애드온에도 그대로 씁니다 (🟨 j02)
  · C ABI 로도 내보낼 수 있습니다 (에러 코드로 변환 · 🔗 f09)

★ 안티패턴
  · 로직 안에서 PyErr 를 직접 만들기
    → 그 함수는 파이썬 없이 테스트할 수 없게 됩니다
  · 모든 에러를 문자열로 뭉개기
    → 사용자가 대응할 수 없고, 로그로도 조사가 안 됩니다

기본 형태

use pyo3::prelude::*;
use pyo3::types::PyAny;

#[pyfunction]
fn apply(py: Python<'_>, data: Vec<f64>, f: &Bound<'_, PyAny>)
    -> PyResult<Vec<f64>>
{
    data.iter()
        .map(|x| f.call1((*x,))?.extract::<f64>())
        .collect()
}
// 파이썬: fastmod.apply([1,2,3], lambda x: x*2)

// 키워드 인자로 부르기
use pyo3::types::PyDict;
let kwargs = PyDict::new(py);
kwargs.set_item("verbose", true)?;
f.call((arg,), Some(&kwargs))?;

// 인자 없이
f.call0()?;

// 진행률 콜백 — 있을 수도 없을 수도
#[pyfunction]
#[pyo3(signature = (data, on_progress = None))]
fn process(py: Python<'_>, data: Vec<f64>, on_progress: Option<&Bound<'_, PyAny>>)
    -> PyResult<f64>
{
    let mut sum = 0.0;
    for (i, x) in data.iter().enumerate() {
        sum += heavy(*x);
        if i % 10_000 == 0 {
            if let Some(cb) = on_progress {
                cb.call1((i as f64 / data.len() as f64,))?;   // 가끔만 ★
            }
        }
    }
    Ok(sum)
}

비용을 알고 쓰세요 ★

파이썬 콜백 1회의 비용
  · 인자를 파이썬 객체로 변환
  · 파이썬 함수 호출 (인터프리터 진입)
  · 반환값을 Rust 타입으로 변환
  → 보통 수백 나노초 ~ 수 마이크로초

★ 100만 개 원소마다 콜백을 부르면
  콜백만으로 0.5~5초입니다. Rust 로 바꾼 의미가 사라집니다.

★ 설계 대안
  ① 콜백 없이 — 결과를 돌려주고 파이썬이 처리하게
       results = fastmod.process(data)
       for r in results: handle(r)          ← 파이썬 루프지만 한 번뿐

  ② 배치 콜백 — n개 처리할 때마다 한 번
       on_progress(done, total)             ← 100번쯤

  ③ 규칙을 데이터로 받기 — 콜백 대신 설정
       fastmod.filter(data, min=0, max=100)  ← Rust 안에서 전부 처리

  ④ 정말 필요하면 표현식을 문자열로 받아 Rust 가 해석
       (polars 의 expression API 가 이 방식입니다) ★

이터레이터로 뒤집기

// 콜백 대신 '결과를 하나씩 내주는' 객체를 돌려줍니다
#[pyclass]
struct Reader { inner: std::vec::IntoIter<Record> }

#[pymethods]
impl Reader {
    fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> { slf }
    fn __next__(&mut self) -> Option<Record> { self.inner.next() }
}

#[pyfunction]
fn read_records(path: &str) -> PyResult<Reader> { }

# 파이썬이 흐름을 제어합니다 — 콜백보다 훨씬 파이썬답습니다 ★
for rec in fastmod.read_records("big.csv"):
    if rec.score > 0.9:
        handle(rec)
        break                    # ★ 중간에 멈출 수도 있습니다

콜백 안에서 난 예외 처리

#[pyfunction]
fn apply_safe(py: Python<'_>, data: Vec<f64>, f: &Bound<'_, PyAny>)
    -> PyResult<Vec<f64>>
{
    let mut out = Vec::with_capacity(data.len());
    for (i, x) in data.iter().enumerate() {
        match f.call1((*x,)) {
            Ok(v) => out.push(v.extract::<f64>()?),
            Err(e) => {
                // ★ 어디서 실패했는지 맥락을 더해 다시 던집니다
                let msg = format!("콜백이 {i} 번째 원소({x})에서 실패");
                let new = PyRuntimeError::new_err(msg);
                new.set_cause(py, Some(e));       // 원인 보존 (y08)
                return Err(new);
            }
        }
    }
    Ok(out)
}

// ❗ 콜백 예외를 삼키지 마세요
//   .unwrap_or(0.0) 로 넘기면 사용자는 왜 결과가 이상한지 알 수 없습니다.
//   실패를 허용하려면 '건너뛴 개수'를 함께 돌려주세요.

// KeyboardInterrupt 도 콜백에서 전파됩니다 — 그대로 두면 됩니다 ★

락 순서가 만드는 데드락 ★

// ❗ 위험: Rust 락을 잡은 채 파이썬 콜백을 부르기
#[pymethods]
impl Registry {
    fn notify(&self, py: Python<'_>) -> PyResult<()> {
        let g = self.state.lock().unwrap();        // ① Rust 락
        for h in &self.handlers {
            h.bind(py).call0()?;                   // ② 파이썬 코드 실행
        }                                          //    → 이 안에서 다시
        Ok(())                                     //      notify() 를 부르면 데드락
    }
}

// ✅ 락을 놓고 부르세요 (🔐 o10 의 원칙)
fn notify(&self, py: Python<'_>) -> PyResult<()> {
    let handlers: Vec<Py<PyAny>> = {
        let g = self.state.lock().unwrap();
        g.handlers.clone()                          // 복사해서 락 해제 ★
    };
    for h in &handlers { h.bind(py).call0()?; }
    Ok(())
}

// 같은 원리로: GIL 을 놓은 스레드가 Rust 락을 기다리고,
// GIL 을 든 스레드가 그 락을 들고 있으면 전체가 멈춥니다.
// → GIL 과 Rust 락을 동시에 잡는 구간을 최소화하세요

Python::with_gil 의 비용과 재진입

// 이미 GIL 을 잡고 있을 때 with_gil 을 다시 불러도 됩니다 (재진입 안전)
Python::with_gil(|py| {
    Python::with_gil(|py2| { })      // ✅ 문제없음 (참조 카운트처럼 동작)
});

// 다만 GIL 이 없는 스레드에서 부르면 '획득 대기' 가 발생합니다
std::thread::spawn(|| {
    Python::with_gil(|py| {          // ★ 여기서 GIL 을 기다립니다
        // 파이썬 메인 스레드가 바쁘면 오래 걸릴 수 있습니다
    });
});

// 비용 측정 (직접 재 보세요 · ⚡ e01)
//   경합 없을 때 with_gil 왕복: 수십~수백 ns
//   경합 있을 때: 스케줄러에 달렸습니다 (밀리초까지)

// ★ 실무 패턴: 결과를 모아 두었다가 한 번에 GIL 을 잡으세요
let results: Vec<f64> = compute_without_gil();
Python::with_gil(|py| { report(py, &results) })?;     // GIL 획득 1회

스텁 파일 만들기

python/fastmod/
├─ __init__.py
├─ __init__.pyi          ★ 파이썬 래퍼의 스텁
├─ _native.pyi           ★ 확장 모듈의 스텁
└─ py.typed              ★ 빈 파일 — "타입 힌트가 있다"는 표시

# python/fastmod/_native.pyi
from typing import Sequence
import numpy as np
import numpy.typing as npt

__version__: str

def sum_squares(n: int) -> int: ...

def tokenize(
    text: str,
    *,
    lowercase: bool = True,
    min_len: int = 1,
) -> list[str]: ...

def mean(a: npt.NDArray[np.float64]) -> float: ...

class Counter:
    total: int
    step: int
    def __init__(self, step: int = 1) -> None: ...
    def increment(self) -> int: ...
    def reset(self) -> None: ...
    @property
    def count(self) -> int: ...
    def __len__(self) -> int: ...

class FastModError(Exception): ...
class ParseError(FastModError): ...

패키징에 포함시키기

# pyproject.toml
[tool.maturin]
python-source = "python"
module-name = "fastmod._native"
include = [
    { path = "python/fastmod/py.typed", format = "wheel" },
    { path = "python/fastmod/*.pyi", format = "wheel" },
]

# 확인 — wheel 안에 들어갔는지
unzip -l target/wheels/*.whl | grep -E "pyi|py.typed"

# mypy 로 검사
pip install mypy
mypy --strict python/

# 사용자 쪽에서 잘 되는지
python -c "
import fastmod
reveal_type(fastmod.sum_squares)   # mypy 로 실행하면 타입이 보입니다"

CI 로 검사합니다

# ① 스텁과 실제 모듈이 맞는지 (mypy 도구)
pip install mypy
stubtest fastmod._native --allowlist stubtest-allowlist.txt
#   → 스텁에 있는데 없는 함수 · 시그니처 불일치를 잡아 줍니다 ★

# ② 스텁 자체가 유효한 파이썬 타입인지
mypy --strict python/fastmod/

# ③ 예제가 실제로 도는지 (doctest)
python -m doctest -v python/fastmod/__init__.py

# GitHub Actions 에 넣기 (🛠️ b08)
#   - run: maturin develop
#   - run: stubtest fastmod._native
#   - run: mypy --strict python/

타입을 정확하게 적기

# numpy 타입
import numpy as np
import numpy.typing as npt

def mean(a: npt.NDArray[np.float64]) -> float: ...
def process(a: npt.ArrayLike) -> npt.NDArray[np.float64]: ...

# 오버로드 — 인자에 따라 반환 타입이 다를 때
from typing import overload, Literal

@overload
def parse(s: str, strict: Literal[True]) -> int: ...
@overload
def parse(s: str, strict: Literal[False] = False) -> int | None: ...

# 제네릭 컨테이너
from collections.abc import Sequence, Iterator
def batch(rows: Sequence[Sequence[float]]) -> list[float]: ...
def stream(path: str) -> Iterator[bytes]: ...

# 파이썬 버전 호환 (3.9 를 지원한다면)
from __future__ import annotations       # list[int] 를 3.9 에서도

# 불투명 핸들
class Handle:
    def __init__(self) -> None: ...
    def close(self) -> None: ...
    def __enter__(self) -> Handle: ...
    def __exit__(self, *args: object) -> None: ...

확장 함수가 파이썬에 보이는 모습

import fastmod, inspect

type(fastmod.sum_squares)
# <class 'builtin_function_or_method'>      ★ 파이썬 함수가 아닙니다

inspect.signature(fastmod.sum_squares)
# ValueError: no signature found for builtin  ← 스텁이 필요한 이유 ★

fastmod.sum_squares.__doc__       # ✅ 이건 있습니다
fastmod.sum_squares.__module__    # ✅
fastmod.sum_squares.__name__      # ✅

# 그래서 다음이 잘 안 됩니다
#   · functools.wraps 로 감싸기
#   · 시그니처 기반 프레임워크 (FastAPI · click · pytest fixture)
#   · dataclass 필드 추론
#
# ★ 해결: 파이썬 래퍼를 두세요 (y02)
#   def sum_squares(n: int) -> int:
#       return _native.sum_squares(n)
#   → 시그니처가 생기고, 검증·문서·데코레이터가 전부 자연스러워집니다

텍스트 시그니처 붙이기

// PyO3 는 __text_signature__ 를 자동 생성합니다
#[pyfunction]
#[pyo3(signature = (n, /, *, verbose = false))]
fn f(n: u64, verbose: bool) { }

// 파이썬에서
//   fastmod.f.__text_signature__  → "(n, /, *, verbose=False)"
//   inspect.signature 가 이걸 읽을 수 있는 경우도 있습니다

// #[pyclass] 도 마찬가지
#[pymethods]
impl Counter {
    #[new]
    #[pyo3(signature = (step = 1))]
    fn new(step: u64) -> Self { }
}

// ★ 그래도 스텁이 정답입니다
//   text_signature 는 기본값 표현이 제한적이고 (복잡한 기본값은 ...),
//   타입 정보를 담지 못합니다.

// 최종 권장 구조
//   _native (Rust)  →  __init__.py (파이썬 래퍼)  →  __init__.pyi (스텁)
//   · 래퍼: 검증 · 기본값 · 편의 함수
//   · 스텁: 타입 · 자동완성
//   · Rust: 계산만

켜는 방법 — 한 줄

# Cargo.toml
[dependencies]
pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }
#                                                          ^^^^^^^^^
#   abi3-py38 / abi3-py39 / abi3-py310 …
#   "이 버전 이상의 CPython 에서 동작" 을 뜻합니다

# pyproject.toml
[project]
requires-python = ">=3.9"        # ★ abi3-py39 와 맞추세요

결과 비교

  abi3 없이 (3.9~3.13 지원)
    fastmod-0.1.0-cp39-cp39-manylinux_2_17_x86_64.whl
    fastmod-0.1.0-cp310-cp310-manylinux_2_17_x86_64.whl
    fastmod-0.1.0-cp311-cp311-manylinux_2_17_x86_64.whl
    fastmod-0.1.0-cp312-cp312-manylinux_2_17_x86_64.whl
    fastmod-0.1.0-cp313-cp313-manylinux_2_17_x86_64.whl
    × (linux/macos/windows) × (x86_64/arm64)  =  30개

  abi3 로
    fastmod-0.1.0-cp39-abi3-manylinux_2_17_x86_64.whl
    × 6 플랫폼  =  6개 ★

  → CI 시간도 5분의 1 이 됩니다 (🛠️ b08)

대가 — 무엇을 포기하나

★ abi3 에서 제한되는 것들 (PyO3 버전에 따라 다르니 문서 확인)
  · 일부 최적화된 C API 호출을 함수 호출로 우회 (미세한 성능 손해)
  · 구조체 내부 필드 직접 접근 불가
  · 일부 타입의 특수 동작 (버전별 차이)

★ 실측 감각
  대부분의 확장에서 성능 차이는 측정 오차 수준입니다.
  경계를 자주 넘는 마이크로 벤치마크에서만 몇 % 보입니다.
  → 직접 재 보고 결정하세요 (⚡ e01)

★ 판단
  · 배포하는 패키지        → abi3 를 켜세요 ★
  · 사내 단일 환경 전용     → 굳이 필요 없습니다
  · 극한 성능이 핵심        → 재서 확인하고 결정

무엇을 빌드할 것인가 ★

최소 권장 세트 (abi3 기준 · 🛠️ b07·b08)

  manylinux x86_64        가장 많이 씁니다 (서버 · CI)
  manylinux aarch64       ARM 서버 · 라즈베리파이
  musllinux x86_64        Alpine 컨테이너 ★ 빠뜨리면 도커에서 컴파일합니다
  macOS x86_64            인텔 맥
  macOS arm64             애플 실리콘 ★
  Windows x86_64          데스크탑 개발자

  + sdist (소스 배포) — 위에 없는 플랫폼은 여기서 컴파일합니다

★ sdist 를 반드시 올리세요
  없으면 지원 안 하는 플랫폼 사용자는 설치 자체가 불가능합니다.
  다만 sdist 로 설치하려면 사용자에게 Rust 툴체인이 필요합니다
  → README 에 명시하세요

설치 실패를 줄이는 장치

# pyproject.toml — 플랫폼 정보를 명확히
[project]
requires-python = ">=3.9"
classifiers = [
    "Operating System :: POSIX :: Linux",
    "Operating System :: MacOS :: MacOS X",
    "Operating System :: Microsoft :: Windows",
    "Programming Language :: Rust",
]

# 순수 파이썬 폴백을 함께 두면 (y01)
# 지원하지 않는 플랫폼에서도 '느리지만 동작' 합니다
try:
    from ._native import process
except ImportError:
    import warnings
    warnings.warn("네이티브 모듈을 쓸 수 없어 순수 파이썬으로 동작합니다")
    from ._pure import process

# 사용자가 겪는 대표 오류와 원인
#   "no matching distribution found"     → 그 플랫폼 wheel 이 없음
#   "error: can't find Rust compiler"    → sdist 로 폴백돼 컴파일 시도 ★
#   "is not a supported wheel"           → 태그 불일치 (y03)

무엇이 '안정' 인가

CPython 의 두 층
  ① 전체 C API — 버전마다 바뀔 수 있습니다 (구조체 필드 포함)
  ② Limited API — 버전 간 유지를 약속한 부분집합 (PEP 384)

abi3 = Limited API 만 쓰고, 그것을 지킨 바이너리 인터페이스

★ 왜 일반 빌드는 버전마다 달라지나
  PyObject 구조체의 내부 배치, 매크로로 인라인된 접근이
  버전마다 바뀝니다. 그래서 3.11 용 .so 를 3.12 에서 로드하면
  "undefined symbol" 이나 크래시가 납니다.

★ abi3 가 하는 일
  구조체를 직접 만지는 대신 함수를 호출합니다.
  그래서 약간 느리지만, 배치가 바뀌어도 동작합니다.

# 검사 도구
pip install abi3audit
abi3audit target/wheels/*.whl        # ★ 정말 abi3 를 지켰는지 검증

abi3 로 못 하는 것을 만났을 때

// feature 로 나눠 두면 둘 다 빌드할 수 있습니다 (🛠️ b04)
// Cargo.toml
// [features]
// abi3 = ["pyo3/abi3-py39"]
// fast = []                       # 버전별 최적화 경로

#[cfg(feature = "fast")]
fn fast_path() { /* 비안정 API 사용 */ }

#[cfg(not(feature = "fast"))]
fn fast_path() { /* 안정 API 로 */ }

// CI 에서
//   기본 배포: --features abi3
//   성능 중시 사용자용: 버전별 wheel 도 함께 (드묾)

// ★ 실무 결론
//   대부분의 확장은 abi3 로 충분합니다.
//   "abi3 때문에 못 하는 것" 을 실제로 만나는 경우는 드물고,
//   만나더라도 파이썬 래퍼로 우회할 수 있는 경우가 많습니다 (y02).

// free-threaded 빌드와의 관계 (y07)
//   3.13t 는 별도 ABI 라 abi3 wheel 이 그대로 쓰이지 않습니다.
//   당분간은 별도 빌드가 필요합니다 — PyO3 문서를 확인하세요.

① ~ ⑥ 빌드와 import ★

① ImportError: dynamic module does not define module export function
   원인  Cargo.toml 의 [lib] name 과 #[pymodule] 함수 이름이 다름
   해결  둘을 맞추거나 pyproject 의 module-name 을 확인 (y02)

② ModuleNotFoundError: No module named 'fastmod'
   원인  maturin develop 을 다른 가상환경에서 실행
   해결  which python / pip show fastmod 로 확인 후 재설치

③ 링크 에러: undefined reference to `PyList_New' (cargo test 할 때)
   원인  extension-module feature 때문에 파이썬 심볼을 안 링크함
   해결  crate-type = ["cdylib", "rlib"] + feature 를 optional 로
         [features] extension-module = ["pyo3/extension-module"]
         cargo test --no-default-features

④ 윈도우에서 링크 실패
   원인  python3xx.lib 를 못 찾음 · 32/64비트 불일치
   해결  같은 비트의 파이썬 사용 · maturin 이 자동 처리하므로
         cargo build 대신 maturin 을 쓰세요 ★

⑤ 바꿨는데 반영이 안 됨
   원인  .so 가 이미 로드된 프로세스 / 캐시
   해결  파이썬 프로세스를 새로 띄우세요 (주피터는 커널 재시작)

⑥ ImportError: ... GLIBC_2.34 not found
   원인  빌드 환경의 glibc 가 실행 환경보다 새로움
   해결  manylinux 컨테이너에서 빌드 (maturin-action 이 처리) (🛠️ b08)

⑦ ~ ⑫ 동작과 성능 ★

⑦ Rust 로 바꿨는데 안 빨라졌다
   원인 1  --release 를 안 붙임 ★ 가장 흔합니다
   원인 2  경계 통과 횟수가 많음 (요소마다 호출) → 배치로 (y01)
   원인 3  list → Vec 변환 비용이 지배적 → numpy 로 (y06)
   원인 4  .clone() 이 루프 안에 있음 (⚡ e02)
   확인    py-spy 로 어디에 시간이 가는지 보세요

⑧ RuntimeError: Already borrowed
   원인  같은 #[pyclass] 인스턴스를 두 번 빌림 (자기 자신을 인자로)
   해결  frozen + Mutex 로 바꾸기 (y05)

⑨ pickle 실패 — cannot pickle 'X' object
   원인  __getstate__/__setstate__ 미구현
   해결  y05 참고 · multiprocessing 을 쓰면 반드시 필요

⑩ Ctrl+C 가 안 먹는다
   원인  GIL 을 놓은 채 오래 도는 중
   해결  주기적으로 py.check_signals() (y07)

⑪ numpy 배열인데 as_slice() 가 None
   원인  연속 배열이 아님 (슬라이스 뷰 · 전치)
   해결  파이썬 래퍼에서 np.ascontiguousarray (y06)

⑫ 세그폴트 — 파이썬이 그냥 죽는다
   원인  unsafe 코드 · FFI · 스레드에서 GIL 없이 파이썬 객체 접근
   해결  아래 진단 절차로

기능 · 안전 ★

□ parity 테스트가 있는가 (기준 구현과 결과 대조) ★
□ 순수 파이썬 폴백이 있는가 (환경 변수로 전환 · y01)
□ 경계 입력을 테스트했는가 (빈 것 · 아주 큰 것 · 잘못된 타입)
□ unwrap()/expect() 가 사용자 입력 경로에 없는가 (y08)
   cargo clippy -- -W clippy::unwrap_used
□ 예외 타입이 적절한가 (전부 RuntimeError 가 아닌가)
□ Ctrl+C 가 동작하는가 (긴 작업이면)
□ 스레드 스트레스 테스트를 했는가 (y07)
□ pickle 이 필요한가 (multiprocessing 사용자가 있다면 · y05)
□ 메모리가 누수되지 않는가
   반복 호출하며 RSS 를 관찰: for _ in range(10**6): f(data)
□ unsafe 를 썼다면 Miri 를 돌렸는가 (🔬 d07)

패키징 · 문서

□ abi3 를 켰는가 (y11)
□ 필요한 플랫폼 wheel 이 전부 있는가 (musllinux 포함)
□ sdist 를 올렸는가
□ py.typed 와 .pyi 가 wheel 에 들어갔는가 (y10)
   unzip -l dist/*.whl | grep -E "pyi|py.typed"
□ stubtest 가 CI 에서 도는가
□ README 에 다음이 있는가
   · 설치 방법 (sdist 로 설치할 때 Rust 필요)
   · 지원 파이썬 · 플랫폼
   · 성능 수치 (측정 환경 명시 ★)
   · 폴백 전환 방법
□ 라이선스가 명확한가 (의존 크레이트 라이선스 포함)
   cargo deny check licenses (🛠️ b09)
□ 버전이 Cargo.toml 과 일치하는가

★ 첫 배포는 TestPyPI 로 먼저 해 보세요
   maturin publish -r testpypi
   pip install -i https://test.pypi.org/simple/ fastmod

재현되지 않는 문제

★ 네이티브 확장의 어려움: 로그가 파이썬에서 끊깁니다

대응 ① 확장 안에서도 로깅
   pyo3-log 크레이트 — Rust 의 log 매크로를 파이썬 logging 으로
     [dependencies] pyo3-log = "0.11"
     pyo3_log::init();          // #[pymodule] 안에서
     log::debug!("입력 크기 {}", n);
   → 파이썬의 logging 설정을 그대로 따릅니다 ★

대응 ② 결정적 재현을 위한 정보 남기기
   · 입력 크기 · 해시 · 버전
   · 실패 시 입력을 파일로 덤프하는 디버그 모드

대응 ③ 프로덕션 프로파일링
   py-spy dump --pid 12345           # 지금 어디서 멈춰 있나
   py-spy top --pid 12345 --native   # 네이티브 프레임까지 ★

대응 ④ 크래시 수집
   리눅스: systemd-coredump · core_pattern
   컨테이너: /proc/sys/kernel/core_pattern 을 호스트에서 설정

되돌릴 수 있는 배포

# ① 런타임 스위치 (y01)
MYPKG_NATIVE=0 python app.py

# ② 버전 고정으로 롤백
pip install fastmod==0.3.2

# ③ 카나리 — 일부 트래픽만 네이티브로
import random, os
_RATIO = float(os.getenv("MYPKG_NATIVE_RATIO", "1.0"))
def process(x):
    if random.random() < _RATIO:
        return _native.process(x)
    return _pure.process(x)

# ④ 결과 대조 모드 — 둘 다 돌려 다르면 로그 ★
def process_verify(x):
    a, b = _native.process(x), _pure.process(x)
    if a != b:
        logger.error("불일치: input=%r native=%r pure=%r", x, a, b)
    return b            # 안전한 쪽을 반환

비교표 ★

★ 한 줄 판단
  브라우저에서 돌아야 한다        → WASM (선택지가 없습니다)
  Node 서버에서 최고 성능이 필요   → 애드온
  Node 인데 배포를 단순하게        → WASM 도 좋은 선택 ★
  파일·네트워크·스레드를 써야 함   → 애드온
  플러그인처럼 신뢰할 수 없는 코드 → WASM (샌드박스)

세 번째 선택지도 있습니다

③ 별도 프로세스 + IPC
   Rust 로 CLI 나 서버를 만들고 JS 가 프로세스를 띄워 통신

   장점
     · 크래시가 Node 를 죽이지 않습니다 ★
     · 언어 경계 문제가 없습니다 (표준 입출력 · HTTP · 유닉스 소켓)
     · 배포가 단순합니다 (실행 파일 하나)
     · 다른 언어에서도 그대로 씁니다
   단점
     · 왕복 지연 (수십 μs ~ 수 ms)
     · 데이터 직렬화 비용
     · 프로세스 관리가 필요합니다

   ★ 이게 정답인 경우가 생각보다 많습니다
     · 호출 빈도가 낮고 데이터가 큰 작업 (이미지 변환 · 빌드 도구)
     · 오래 도는 작업 (인덱싱 · 컴파일)
     · CLI 로도 쓸모가 있는 기능

④ 그냥 JS 로 두기
   Node 는 생각보다 빠릅니다. V8 의 JIT 는 뜨거운 루프를 잘 최적화합니다.
   측정 없이 네이티브로 옮기지 마세요 (🐍 y01 과 같은 원칙 · ⚡ e01)

호출 횟수를 먼저 봅니다 ★

// ❌ 요소마다 경계를 넘음
const results = rows.map(r => native.process(r));   // 100만 번

// ✅ 배치
const results = native.processBatch(rows);          // 1번

// ✅✅ 이미 메모리에 있는 버퍼를 그대로 (j04)
const out = native.processBuffer(inputBuffer);      // 복사도 없음

경계 통과 비용 감각 (직접 재 보세요 · ⚡ e01)
  napi-rs 빈 함수 호출     대략 수십~수백 ns
  WASM 빈 함수 호출        더 쌉니다 (같은 프로세스·같은 VM)
  숫자 전달                거의 공짜
  문자열 전달              길이에 비례해 복사 (UTF-16 ↔ UTF-8 변환 ★)
  Buffer 전달              제로카피 가능 (j04)

★ 문자열이 의외의 함정입니다
  JS 문자열은 UTF-16, Rust 는 UTF-8 이라 매번 변환됩니다.
  대량 텍스트는 Buffer(바이트)로 주고받는 편이 훨씬 빠릅니다.

이벤트 루프를 막지 않기

★ Node 에서 가장 중요한 제약

  동기 함수가 100ms 걸리면
  그동안 서버는 아무 요청도 처리하지 못합니다.

  판단 기준
    < 1ms     동기로 두세요 (비동기 오버헤드가 더 큽니다)
    1~10ms    상황에 따라 (요청당 한 번이면 동기도 가능)
    > 10ms    반드시 비동기로 (j05) ★

  비동기로 만드는 방법
    · napi-rs 의 AsyncTask — 스레드 풀에서 실행
    · #[napi] async fn — tokio 런타임 사용
    · 둘 다 Promise 를 반환합니다

  WASM 은?
    WASM 도 동기로 돌면 메인 스레드를 막습니다.
    브라우저에서는 Web Worker 로, Node 에서는 worker_threads 로 옮기세요.

예전에는 Node 버전마다 다시 빌드했습니다

과거 (nan · V8 API 직접 사용)
  · V8 의 C++ API 는 Node 마이너 버전마다 바뀌었습니다
  · Node 12 용 애드온을 Node 14 에서 로드하면 크래시
  · npm install 마다 재컴파일 (node-gyp) → 설치 실패의 주범

현재 (N-API / Node-API)
  · C ABI 기반의 안정 인터페이스 ★
  · 한 번 빌드하면 Node 버전이 바뀌어도 그대로 동작
  · Electron · Deno · Bun 도 지원

  NAPI_VERSION 으로 최소 요구 버전을 정합니다
    NAPI_VERSION=8  → Node 12.22+ 정도

★ 파이썬의 abi3 와 같은 아이디어입니다 (🐍 y11)
  "구조체를 직접 만지지 말고 함수로 호출하라"

# 확인
node -p "process.versions.napi"      # 이 Node 가 지원하는 N-API 버전

napi-rs 가 그 위에서 하는 일

N-API 는 C 인터페이스라 그대로 쓰면 장황합니다.
napi-rs 는 매크로로 그것을 감춥니다.

  #[napi]
  fn add(a: i32, b: i32) -> i32 { a + b }

  ↓ 매크로가 생성하는 것 (개념)

  · napi_value 인자를 i32 로 변환하는 코드
  · 타입이 안 맞으면 TypeError 를 던지는 코드
  · 결과를 napi_value 로 변환
  · 모듈 등록 코드
  · TypeScript 타입 정의(.d.ts) 생성 ★  ← 이게 큰 이점입니다

# 생성된 코드 보기
cargo expand --lib

★ .d.ts 자동 생성은 파이썬 쪽(.pyi 를 손으로 · 🐍 y10)보다 나은 점입니다.
  타입이 코드와 어긋날 수 없습니다.

처음부터 끝까지

# ① 프로젝트 생성 — 뼈대를 전부 만들어 줍니다
npm create napi@latest fastmod
# 또는
npx @napi-rs/cli new fastmod
cd fastmod

# 만들어지는 것
#   Cargo.toml       Rust 설정
#   package.json     npm 설정 + 빌드 스크립트
#   src/lib.rs       여기에 코드를 씁니다
#   index.js         플랫폼별 .node 를 골라 로드하는 로더 (자동 생성)
#   index.d.ts       TypeScript 타입 (자동 생성) ★

# ② 빌드
npm run build          # napi build --platform --release
                       # → fastmod.linux-x64-gnu.node + index.d.ts

# ③ 써 보기
node -e "console.log(require('./index.js').sumSquares(1000))"

코드 두 곳

// src/lib.rs
#![deny(clippy::all)]

use napi_derive::napi;

/// 1..n 의 제곱합
#[napi]
pub fn sum_squares(n: u32) -> u32 {
    (1..=n).map(|x| x * x).sum()
}

#[napi]
pub fn count_words(text: String) -> u32 {
    text.split_whitespace().count() as u32
}

// ★ 함수 이름은 자동으로 camelCase 가 됩니다
//   sum_squares → sumSquares
//   그대로 두려면 #[napi(js_name = "sum_squares")]

# Cargo.toml
[package]
name = "fastmod"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]        # ★ (🔗 f02)

[dependencies]
napi = { version = "2", default-features = false, features = ["napi4"] }
napi-derive = "2"

[build-dependencies]
napi-build = "2"

[profile.release]
lto = true
strip = "symbols"              # 바이너리 크기 (🛠️ b10)

// build.rs
fn main() { napi_build::setup(); }

package.json 의 핵심

{
  "name": "fastmod",
  "version": "0.1.0",
  "main": "index.js",
  "types": "index.d.ts",
  "napi": {
    "name": "fastmod",
    "triples": {
      "defaults": true,
      "additional": [
        "aarch64-apple-darwin",
        "aarch64-unknown-linux-gnu",
        "x86_64-unknown-linux-musl"
      ]
    }
  },
  "scripts": {
    "build": "napi build --platform --release",
    "build:debug": "napi build --platform",
    "test": "node --test",
    "artifacts": "napi artifacts",
    "prepublishOnly": "napi prepublish -t npm"
  },
  "devDependencies": { "@napi-rs/cli": "^2" },
  "files": ["index.js", "index.d.ts"],
  "engines": { "node": ">= 12" }
}

개발 흐름

# 반복 개발
npm run build:debug && node test.js

# 파일이 바뀌면 자동
cargo install cargo-watch
cargo watch -s "npm run build:debug && node --test"

# Rust 쪽 단위 테스트 (napi 없이 도는 순수 로직만 · r11)
cargo test

# ★ 구조 권장: 로직과 바인딩을 분리하세요
#   src/core.rs   순수 Rust 로직 — cargo test 가 그대로 돕니다
#   src/lib.rs    #[napi] 바인딩만 — 얇게

# 타입 정의만 다시 생성
napi build --platform --release --dts index.d.ts

# 여러 진입점 (ESM + CJS)
#   package.json 의 exports 필드를 쓰세요
#   "exports": { "require": "./index.js", "import": "./index.mjs" }

플랫폼 판별과 폴백

// napi 가 생성하는 index.js 의 요약
const { platform, arch } = process
let nativeBinding = null

switch (platform) {
  case 'linux':
    // glibc 인지 musl 인지 판별 ★
    const isMusl = !process.report ||
      !/glibc|GNU/.test(process.report.getReport().header.glibcVersionRuntime)
    if (arch === 'x64') {
      nativeBinding = isMusl
        ? require('fastmod-linux-x64-musl')
        : require('fastmod-linux-x64-gnu')
    }
    break
  case 'darwin': /* … */
  case 'win32':  /* … */
}

if (!nativeBinding) throw new Error(`지원하지 않는 플랫폼: ${platform}-${arch}`)
module.exports = nativeBinding

// ★ musl 판별을 빠뜨리면 Alpine 도커에서 로드가 실패합니다.
//   가장 흔한 배포 사고 중 하나입니다 (j10)

.node 파일의 정체

# .node 는 그냥 공유 라이브러리입니다 (확장자만 다름)
file fastmod.linux-x64-gnu.node
#   ELF 64-bit LSB shared object, x86-64

# 내보내는 심볼
nm -D fastmod.linux-x64-gnu.node | grep napi_register
#   napi_register_module_v1    ★ Node 가 이걸 찾습니다

# 의존성 확인 — 순수 Rust 라면 아주 적습니다
ldd fastmod.linux-x64-gnu.node
#   libgcc_s.so.1 · libc.so.6 정도

# 크기 확인 (🛠️ b10)
ls -lh *.node
#   보통 수백 KB ~ 수 MB
#   strip = "symbols" · lto = true · opt-level = "z" 로 줄일 수 있습니다

# Electron 에서 쓰려면
#   같은 .node 가 그대로 동작합니다 (N-API 덕분 · j01)
#   단, Electron 버전의 N-API 지원 범위를 확인하세요

객체 주고받기

use napi_derive::napi;

// JS 평범한 객체 ↔ Rust 구조체 ★
#[napi(object)]
pub struct Point { pub x: f64, pub y: f64 }

#[napi(object)]
pub struct Result {
    pub count: u32,
    pub items: Vec<String>,
    pub meta: Option<Point>,
}

#[napi]
pub fn analyze(points: Vec<Point>) -> Result {
    Result {
        count: points.len() as u32,
        items: points.iter().map(|p| format!("{},{}", p.x, p.y)).collect(),
        meta: points.first().cloned(),
    }
}

// 필드 이름은 camelCase 로 변환됩니다
#[napi(object)]
pub struct Config {
    pub max_size: u32,          // JS 에서는 maxSize
    #[napi(js_name = "url")]
    pub endpoint: String,       // 이름을 직접 지정
}

const r = native.analyze([{ x: 1, y: 2 }, { x: 3, y: 4 }])
// { count: 2, items: ['1,2', '3,4'], meta: { x: 1, y: 2 } }

변환 비용을 알기 ★

#[napi(object)] 은 '복사' 입니다
  JS 객체의 각 필드를 읽어 Rust 구조체를 만듭니다.
  → 객체 100만 개를 넘기면 100만 번의 프로퍼티 조회가 일어납니다.

★ 대안
  ① 배열로 평탄화 — 프로퍼티 조회가 사라집니다
       xs: Float64Array, ys: Float64Array
  ② Buffer 로 직렬화 (j04)
  ③ 객체 대신 개별 인자

측정 감각 (직접 재 보세요 · ⚡ e01)
  숫자 인자 하나          거의 공짜
  문자열 (짧음)           UTF-16 → UTF-8 변환 (수백 ns)
  문자열 (1MB)            복사 + 변환 (밀리초 단위)
  객체 (필드 5개)         프로퍼티 조회 5회
  Vec<f64> 100만          수십 ms ★
  Float64Array 100만      제로카피 가능 (j04) ★

옵션 객체 · 기본값

#[napi(object)]
pub struct TokenizeOptions {
    pub lowercase: Option<bool>,
    pub min_len: Option<u32>,
}

#[napi]
pub fn tokenize(text: String, options: Option<TokenizeOptions>) -> Vec<String> {
    let o = options.unwrap_or(TokenizeOptions { lowercase: None, min_len: None });
    let lowercase = o.lowercase.unwrap_or(true);      // ★ 기본값은 Rust 에서
    let min_len = o.min_len.unwrap_or(1) as usize;
    // …
}

native.tokenize("A B")                       // 기본값
native.tokenize("A B", { lowercase: false }) // 일부만 ★ JS 관례

// 얇은 JS 래퍼를 두면 더 유연합니다 (🐍 y02 와 같은 원칙)
// index.js 대신 wrapper.js 를 main 으로 두고
//   const native = require('./index.js')
//   exports.tokenize = (text, opts = {}) => {
//     if (typeof text !== 'string') throw new TypeError('text must be string')
//     return native.tokenize(text, opts)
//   }

숫자 타입 함정 ★

JS 의 number 는 f64 입니다 — 정수는 2^53 까지만 정확합니다.

  #[napi] fn f(n: i64) -> i64      → TS 에서 bigint
  #[napi] fn g(n: i32) -> i32      → TS 에서 number ✅
  #[napi] fn h(n: f64) -> f64      → number ✅

★ 실무 권장
  · 카운트·인덱스는 u32/i32 로 (40억까지면 대부분 충분)
  · 진짜 큰 수는 bigint 를 받아들이거나 문자열로
  · 타임스탬프(ms)는 f64 로 두면 2^53ms ≈ 28만년까지 안전합니다

오버플로 동작
  u32 자리에 -1 을 주면?          → 변환 에러 (napi 가 검사)
  u32 자리에 2^40 을 주면?        → 변환 에러
  f64 자리에 NaN 을?              → NaN 그대로 들어옵니다 ★ 직접 검사하세요

  if !x.is_finite() {
      return Err(Error::new(Status::InvalidArg, "유한한 수여야 합니다"));
  }

napi_value 는 핸들입니다

napi_value 는 V8 객체를 가리키는 '핸들' 입니다.
GC 가 객체를 옮겨도 핸들은 유효합니다 (간접 참조).

★ 중요한 제약
  핸들은 '핸들 스코프' 안에서만 유효합니다.
  함수가 반환되면 그 스코프가 닫히고 핸들이 무효가 됩니다.
  → JS 값을 Rust 구조체에 저장하려면 Reference 를 만들어야 합니다.

  use napi::bindgen_prelude::*;
  let r: Ref<JsObject> = obj.create_ref()?;    // GC 로부터 보호
  // 나중에
  let obj = r.get_value(&env)?;
  r.unref(env)?;                                // ★ 반드시 해제

  napi-rs 의 고수준 타입(String · Vec · #[napi(object)])은
  전부 '값을 Rust 로 복사' 하므로 이 문제가 없습니다.
  그래서 대부분의 코드에서는 신경 쓸 일이 없습니다. ★

성능을 재고 확인하기

// 경계 통과 비용만 재기
const { performance } = require('perf_hooks')
const native = require('./index.js')

function bench(name, fn, n = 1_000_000) {
  fn()                                   // 워밍업 (JIT)
  const t = performance.now()
  for (let i = 0; i < n; i++) fn()
  console.log(name, ((performance.now() - t) * 1e6 / n).toFixed(1), 'ns/op')
}

bench('noop', () => native.noop())
bench('add', () => native.add(1, 2))
bench('string', () => native.echo('hello'))
bench('object', () => native.point({ x: 1, y: 2 }))

// ★ JS 로 같은 일을 하는 함수와 비교하세요
bench('js add', () => 1 + 2)
//   → 경계 통과가 계산보다 훨씬 비싸다는 것이 눈으로 보입니다

// 정확한 벤치마크는 전용 도구로
//   npm i -D mitata   또는  tinybench

읽기 · 쓰기

use napi::bindgen_prelude::*;
use napi_derive::napi;

// 읽기 — 복사 없음 ★
#[napi]
pub fn checksum(data: Buffer) -> u32 {
    let bytes: &[u8] = &data;            // Deref 로 슬라이스 (🔐 o07)
    bytes.iter().fold(0u32, |a, b| a.wrapping_add(*b as u32))
}

// 제자리 수정 — 할당조차 없습니다
#[napi]
pub fn invert(mut data: Buffer) {
    let bytes: &mut [u8] = &mut data;
    for b in bytes.iter_mut() { *b = !*b; }
}

// 새 Buffer 반환 (Vec 을 그대로 넘김 — 복사 1회)
#[napi]
pub fn compress(data: Buffer) -> Result<Buffer> {
    let out: Vec<u8> = do_compress(&data)?;
    Ok(out.into())                        // ★ Vec<u8> → Buffer
}

// TypedArray
#[napi]
pub fn scale(mut a: Float64Array, k: f64) {
    for x in a.iter_mut() { *x *= k; }
}
#[napi]
pub fn sum_i32(a: Int32Array) -> i64 {
    a.iter().map(|x| *x as i64).sum()
}

JS 쪽에서

const fs = require('fs')
const native = require('./index.js')

// 파일을 읽어 그대로 넘기기 — 복사 없음 ★
const buf = fs.readFileSync('image.png')
const sum = native.checksum(buf)

// 제자리 수정
native.invert(buf)          // buf 가 직접 바뀝니다

// TypedArray
const arr = new Float64Array(1_000_000)
native.scale(arr, 2.0)      // 제로카피

// ArrayBuffer 공유 확인
const view = new Uint8Array(buf.buffer, buf.byteOffset, buf.length)
// ★ Buffer 는 ArrayBuffer 위의 뷰입니다. offset 을 잊지 마세요

출력 버퍼를 받는 설계 ★

// ❌ 매번 새 Buffer — 초당 수천 프레임이면 GC 압력이 큽니다
#[napi]
pub fn process(input: Buffer) -> Buffer { }

// ✅ 호출자가 버퍼를 재사용
#[napi]
pub fn process_into(input: Buffer, mut output: Buffer) -> Result<u32> {
    let src: &[u8] = &input;
    let dst: &mut [u8] = &mut output;
    if dst.len() < src.len() {
        return Err(Error::new(Status::InvalidArg, "출력 버퍼가 작습니다"));
    }
    for (d, s) in dst.iter_mut().zip(src) { *d = s.wrapping_add(1); }
    Ok(src.len() as u32)
}

// 버퍼를 한 번 만들어 재사용
const out = Buffer.allocUnsafe(1920 * 1080 * 4)
for await (const frame of frames) {
  const n = native.processInto(frame, out)
  await sink.write(out.subarray(0, n))
}

스트림과 청크 처리

// 상태를 이어 가는 스트리밍 처리기
#[napi]
pub struct Hasher { inner: blake3::Hasher }

#[napi]
impl Hasher {
    #[napi(constructor)]
    pub fn new() -> Self { Hasher { inner: blake3::Hasher::new() } }

    #[napi]
    pub fn update(&mut self, chunk: Buffer) { self.inner.update(&chunk); }

    #[napi]
    pub fn digest(&self) -> Buffer { self.inner.finalize().as_bytes().to_vec().into() }
}

const h = new native.Hasher()
for await (const chunk of fs.createReadStream('big.bin')) {
  h.update(chunk)                    // 청크마다 제로카피
}
console.log(h.digest().toString('hex'))

// ★ 청크 크기는 64KB~1MB 정도가 무난합니다.
//   너무 작으면 경계 통과 횟수가 늘고 (j01),
//   너무 크면 이벤트 루프를 오래 막습니다 (j05)

스레드 간 진짜 공유

// worker_threads 와 SharedArrayBuffer
const { Worker } = require('worker_threads')
const sab = new SharedArrayBuffer(1024 * 1024)
const view = new Uint8Array(sab)

const w = new Worker('./worker.js', { workerData: { sab } })
// 워커와 메인이 같은 메모리를 봅니다 — 복사가 없습니다 ★

// Rust 쪽에서 받기
#[napi]
pub fn process_shared(mut data: Uint8Array) {
    let bytes: &mut [u8] = &mut data;
    // ❗ 다른 스레드가 동시에 이 메모리를 만질 수 있습니다
    //    데이터 경쟁을 언어가 막아 주지 못하는 드문 자리입니다 (⚡ e06)
    //    → 원자 연산을 쓰거나, 영역을 나눠 쓰기로 약속하세요
}

// 영역 분할이 가장 안전합니다 (🔐 o02 의 split_at_mut 과 같은 아이디어)
#[napi]
pub fn process_range(mut data: Uint8Array, start: u32, len: u32) {
    let s = &mut data[start as usize..(start + len) as usize];
    // 워커마다 겹치지 않는 범위를 담당
}

복사가 실제로 일어나는지 확인

// ① 메모리 사용량으로 확인
const before = process.memoryUsage()
const buf = Buffer.allocUnsafe(100 * 1024 * 1024)   // 100MB
native.checksum(buf)
const after = process.memoryUsage()
console.log('external', (after.external - before.external) / 1e6, 'MB')
// 제로카피면 거의 늘지 않습니다 ★

// ② 시간으로 확인 — 크기에 비례하면 복사입니다
for (const n of [1e3, 1e5, 1e7]) {
  const b = Buffer.allocUnsafe(n)
  const t = performance.now()
  native.noop(b)
  console.log(n, performance.now() - t)
}
// 제로카피면 크기와 무관하게 일정합니다

// ③ 제자리 수정으로 확인 (가장 확실)
const b = Buffer.from([1, 2, 3])
native.invert(b)
console.log(b)     // 바뀌었으면 같은 메모리를 본 것입니다 ★

① AsyncTask — 스레드 풀에서

use napi::{Task, Env, JsNumber, Result};
use napi_derive::napi;

pub struct HeavyTask { data: Vec<f64> }

impl Task for HeavyTask {
    type Output = f64;
    type JsValue = JsNumber;

    // ★ 이 부분이 워커 스레드에서 돕니다 (JS 를 만질 수 없습니다)
    fn compute(&mut self) -> Result<f64> {
        Ok(self.data.iter().map(|x| expensive(*x)).sum())
    }

    // 결과를 JS 값으로 (메인 스레드에서 호출됨)
    fn resolve(&mut self, env: Env, out: f64) -> Result<JsNumber> {
        env.create_double(out)
    }
}

#[napi(ts_return_type = "Promise<number>")]
pub fn heavy_async(data: Vec<f64>) -> AsyncTask<HeavyTask> {
    AsyncTask::new(HeavyTask { data })
}

const result = await native.heavyAsync(data)   // 이벤트 루프가 안 막힙니다 ★

② async fn — tokio 런타임

# Cargo.toml
[dependencies]
napi = { version = "2", features = ["napi4", "async", "tokio_rt"] }
tokio = { version = "1", features = ["fs", "time", "rt-multi-thread"] }

#[napi]
pub async fn read_file(path: String) -> Result<Buffer> {
    let data = tokio::fs::read(path).await
        .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))?;
    Ok(data.into())
}

#[napi]
pub async fn fetch_and_parse(url: String) -> Result<String> {
    let body = reqwest::get(&url).await?.text().await?;
    Ok(parse(&body))
}

// ★ CPU 작업을 async fn 안에서 직접 하면 안 됩니다
//   tokio 워커를 막습니다 → spawn_blocking 으로
#[napi]
pub async fn mixed(data: Vec<f64>) -> Result<f64> {
    let n = tokio::task::spawn_blocking(move || heavy(&data)).await
        .map_err(|e| Error::from_reason(e.to_string()))?;
    Ok(n)
}

비동기도 공짜가 아닙니다 ★

AsyncTask 한 번의 추가 비용
  · 스레드 풀에 작업 큐잉
  · 컨텍스트 스위치
  · 결과를 메인 스레드로 전달 (이벤트 루프 한 바퀴)
  · Promise 생성·해결
  → 보통 수십 μs 수준입니다 (직접 재 보세요 · ⚡ e01)

★ 판단표
  작업 시간     권장
  < 100 μs      동기 ★ (비동기 오버헤드가 작업보다 큽니다)
  100μs ~ 1ms   동기 (요청당 몇 번이면)
  1 ~ 10ms      상황에 따라 — 처리량 요구를 보세요
  > 10ms        비동기 필수

★ 둘 다 제공하는 것이 좋은 API 입니다
  #[napi] pub fn hash_sync(data: Buffer) -> Buffer
  #[napi] pub fn hash(data: Buffer) -> AsyncTask<HashTask>
  (Node 표준 라이브러리도 fs.readFileSync / fs.readFile 로 둘 다 줍니다)

이벤트 루프 지연 측정하기

// 내 애드온이 루프를 막고 있는지 확인 ★
const { monitorEventLoopDelay } = require('perf_hooks')
const h = monitorEventLoopDelay({ resolution: 10 })
h.enable()

// 부하를 주고
for (let i = 0; i < 100; i++) native.heavySync(data)

h.disable()
console.log('평균', h.mean / 1e6, 'ms')
console.log('최대', h.max / 1e6, 'ms')      // ★ 이 값이 크면 막고 있는 것

// 운영에서는 지표로 내보내세요
//   p99 이벤트 루프 지연이 급증하면 동기 네이티브 호출을 의심

// 부하 테스트로 확인
//   autocannon -c 100 -d 10 http://localhost:3000/api
//   동기 버전과 비동기 버전의 p99 를 비교하면 차이가 명확합니다

풀을 누가 함께 쓰나

libuv 스레드 풀(기본 4개)을 쓰는 것들
  · fs.* 비동기 함수 (readFile 등)
  · dns.lookup
  · zlib · crypto 의 일부
  · napi_create_async_work → AsyncTask ★

→ 내 애드온이 풀을 오래 점유하면 fs 도 느려집니다.

★ 대응
  ① UV_THREADPOOL_SIZE 를 늘리기 (최대 1024, 보통 코어 수 × 2)
     프로세스 시작 전에 설정해야 합니다 ★
     process.env 로 런타임에 바꿔도 안 먹습니다

  ② 긴 작업은 자체 스레드 풀로 (tokio · rayon)
     libuv 풀을 건드리지 않습니다

  ③ 아주 긴 작업은 worker_threads 나 별도 프로세스로 (j01)

# 현재 값 확인
node -e "console.log(process.env.UV_THREADPOOL_SIZE || 4)"

async fn 과 tokio 런타임의 관계

napi-rs 의 tokio_rt feature 는
프로세스당 tokio 멀티스레드 런타임을 하나 만듭니다.

★ 주의할 점
  · 그 런타임의 워커 스레드는 Node 이벤트 루프와 별개입니다
  · async fn 안에서 블로킹 호출을 하면 tokio 워커가 막힙니다
      std::fs::read()      ❌ 블로킹
      tokio::fs::read()    ✅
      무거운 계산          → spawn_blocking

  · 런타임 종료 순서 문제 (🔐 o07 의 Drop 순서)
      프로세스 종료 시 tokio 태스크가 남아 있으면 행이 걸릴 수 있습니다
      → 종료 훅에서 정리하거나 타임아웃을 두세요

  · Node 의 async_hooks · AsyncLocalStorage 컨텍스트는
    네이티브 비동기 경계를 넘어가지 않습니다 ★
    → 요청 컨텍스트(트레이싱 ID 등)를 인자로 명시적으로 넘기세요

# tokio 런타임 스레드 확인
#   리눅스: ls /proc/$(pgrep -n node)/task | wc -l

Promise 를 직접 만들기

use napi::bindgen_prelude::*;
use napi::{Env, JsObject, Result};

// ① async fn 이 가장 간단합니다 (j05)
#[napi]
pub async fn simple() -> Result<u32> { Ok(42) }

// ② 직접 deferred 로 (외부 이벤트를 기다릴 때)
#[napi(ts_return_type = "Promise<number>")]
pub fn manual(env: Env) -> Result<JsObject> {
    let (deferred, promise) = env.create_deferred()?;

    std::thread::spawn(move || {
        std::thread::sleep(std::time::Duration::from_millis(100));
        match compute() {
            Ok(v) => deferred.resolve(move |_env| Ok(v)),   // ★ 메인 스레드에서 실행
            Err(e) => deferred.reject(Error::from_reason(e.to_string())),
        }
    });

    Ok(promise)
}

// ★ deferred 는 Send 입니다 — 다른 스레드로 넘겨도 됩니다.
//   resolve 클로저는 메인 스레드에서 실행되므로 JS 를 만질 수 있습니다.

ThreadsafeFunction — 콜백 ★

use napi::threadsafe_function::{
    ThreadsafeFunction, ThreadsafeFunctionCallMode, ErrorStrategy,
};

#[napi]
pub fn watch(
    #[napi(ts_arg_type = "(progress: number) => void")]
    callback: JsFunction,
) -> Result<()> {
    let tsfn: ThreadsafeFunction<f64, ErrorStrategy::Fatal> =
        callback.create_threadsafe_function(0, |ctx| {
            ctx.env.create_double(ctx.value).map(|v| vec![v])
        })?;

    std::thread::spawn(move || {
        for i in 0..=100 {
            std::thread::sleep(std::time::Duration::from_millis(50));
            tsfn.call(i as f64 / 100.0, ThreadsafeFunctionCallMode::NonBlocking);
        }
        // 마지막에 반드시 해제 — 안 하면 프로세스가 안 끝납니다 ★
        tsfn.abort().ok();
    });

    Ok(())
}

native.watch(p => console.log(`${(p * 100).toFixed(0)}%`))

콜백은 비쌉니다 ★

tsfn.call 한 번의 경로
  워커 스레드 → 큐에 넣기 → 이벤트 루프 깨우기
  → 메인 스레드에서 JS 값 생성 → JS 함수 호출

  → 보통 수 μs 이상입니다 (직접 재 보세요 · ⚡ e01)

★ 100만 번 부르면 콜백만으로 수 초입니다.
  파이썬 콜백과 같은 문제입니다 (🐍 y09).

설계 대안
  ① 배치로 — n개마다 한 번, 또는 시간 간격으로
       if last.elapsed() > Duration::from_millis(100) { tsfn.call(..) }
  ② 결과를 모아 한 번에 반환 (콜백 없이)
  ③ 진행률은 '값'이 아니라 '공유 카운터'로
       AtomicU64 를 두고 JS 가 주기적으로 폴링
  ④ 정말 스트림이 필요하면 Node 스트림 API 로 감싸기

★ 가장 흔한 좋은 선택: ①번 시간 기반 스로틀링
  사람이 보는 진행률은 초당 10회면 충분합니다.

JS 래퍼로 다듬기

// 네이티브의 콜백 API 를 JS 관용구로 감싸기
const { EventEmitter } = require('events')
const native = require('./index.js')

class Watcher extends EventEmitter {
  constructor(path) {
    super()
    this._inner = new native.Watcher()
    this._inner.onChange(ev => this.emit(ev.kind, ev.path))
  }
  close() { this._inner.close() }
}

// 또는 AsyncIterator 로
async function* watch(path) {
  const queue = []
  let notify
  const w = new native.Watcher()
  w.onChange(ev => { queue.push(ev); notify?.() })
  try {
    while (true) {
      if (queue.length === 0) await new Promise(r => { notify = r })
      yield queue.shift()
    }
  } finally { w.close() }         // ★ 정리를 보장
}

ref / unref 의 의미

// tsfn 은 기본적으로 이벤트 루프를 '붙잡습니다' (ref)
// → 살아 있는 동안 Node 가 종료되지 않습니다

tsfn.unref(&env)?;     // 붙잡지 않기 — 다른 일이 없으면 종료 허용 ★
tsfn.refer(&env)?;     // 다시 붙잡기
tsfn.abort()?;         // 완전히 해제 (이후 call 은 실패)

// ★ 언제 unref 하나
//   · 백그라운드 감시자처럼 '있어도 종료를 막으면 안 되는' 것
//   · setInterval 의 unref() 와 같은 개념입니다

// 정리 순서 문제
//   프로세스 종료 시 워커 스레드가 아직 tsfn.call 을 하면?
//   → abort 이후의 call 은 조용히 실패합니다 (크래시는 아님)
//   → 하지만 워커가 Rust 자원을 정리하지 못할 수 있습니다

// 안전한 종료 패턴
//   ① JS 쪽에서 close() 를 명시적으로 부르게 만들기 ★
//   ② process.on('exit') 훅에서 정리
//   ③ Rust 쪽에 종료 플래그를 두고 워커가 확인

디버깅 — 프로세스가 안 끝날 때

// 무엇이 이벤트 루프를 붙잡고 있나
const wtf = require('why-is-node-running')   // npm i -D why-is-node-running
setTimeout(() => wtf(), 5000)

// Node 내장으로
process.on('beforeExit', () => console.log('종료 직전'))
console.log(process._getActiveHandles().length)
console.log(process._getActiveRequests().length)

// ★ 네이티브 애드온이 원인이면 위 목록에 잘 안 잡힙니다.
//   그럴 때는 tsfn 을 의심하세요.

// 강제 종료 (최후의 수단 — Drop 이 안 불립니다 · 🔐 o07)
process.exit(0)

// 검증 테스트를 하나 두세요
//   test('종료된다', async () => {
//     const w = new native.Watcher(); w.close()
//     // 이 테스트 파일이 타임아웃 없이 끝나면 OK ★
//   })

기본 형태

use napi_derive::napi;
use regex::Regex;

#[napi]
pub struct Matcher {
    re: Regex,                       // 내부 필드 (JS 에 안 보임)
    pub count: u32,                  // pub 이면 속성으로 노출 ★
}

#[napi]
impl Matcher {
    #[napi(constructor)]
    pub fn new(pattern: String) -> Result<Self> {
        let re = Regex::new(&pattern)
            .map_err(|e| Error::new(Status::InvalidArg, e.to_string()))?;
        Ok(Matcher { re, count: 0 })
    }

    #[napi]
    pub fn find_all(&mut self, text: String) -> Vec<String> {
        self.count += 1;
        self.re.find_iter(&text).map(|m| m.as_str().to_string()).collect()
    }

    #[napi(getter)]
    pub fn pattern(&self) -> String { self.re.as_str().to_string() }

    #[napi(setter)]
    pub fn set_count(&mut self, v: u32) { self.count = v; }

    #[napi(factory)]                 // static 생성자
    pub fn from_words(words: Vec<String>) -> Result<Self> { }

    #[napi]
    pub fn to_string(&self) -> String { format!("Matcher({})", self.re) }
}

const m = new native.Matcher('\\d+')
m.findAll('a1 b22')       // ['1', '22']
m.count                   // 1
m.pattern                 // '\\d+'  (getter)

object vs class ★

★ 고르는 기준 (🐍 y05 와 같습니다)
  · 그냥 값 묶음이면          → object
  · 초기화가 비싸면           → class
  · 상태를 이어 가야 하면      → class
  · 정리가 필요하면(파일·연결) → class + close()

★ 성능
  object 는 필드마다 프로퍼티 조회가 일어납니다 (j03).
  class 는 핸들 하나만 오가므로 큰 상태를 여러 번 쓸 때 훨씬 쌉니다.

비동기 메서드 만들기

// 클래스 메서드도 Promise 를 반환할 수 있습니다 (j05)
#[napi]
impl Db {
    #[napi]
    pub async fn query_async(&self, sql: String) -> Result<Vec<Row>> {
        // ❗ &self 를 워커 스레드로 넘길 수 없습니다
        //    → 필요한 것을 복제하거나 Arc 로 공유하세요 (🔐 o10)
    }
}

// ✅ 내부 상태를 Arc 로
#[napi]
pub struct Db { inner: Arc<Pool> }

#[napi]
impl Db {
    #[napi]
    pub async fn query(&self, sql: String) -> Result<Vec<Row>> {
        let pool = self.inner.clone();               // ★ Arc clone (쌈)
        tokio::task::spawn_blocking(move || pool.query(&sql))
            .await
            .map_err(|e| Error::from_reason(e.to_string()))?
    }
}

// AsyncTask 를 쓸 때도 같은 원칙
#[napi]
pub fn process(&self, data: Buffer) -> AsyncTask<ProcessTask> {
    AsyncTask::new(ProcessTask {
        state: self.inner.clone(),         // 공유
        data: data.to_vec(),               // 복사 (Buffer 는 워커로 못 넘김)
    })
}

worker_threads 와의 관계

★ 중요: 클래스 인스턴스는 워커 스레드로 전달되지 않습니다

  const w = new Worker('./w.js', { workerData: { matcher } })
  // ❌ DataCloneError — 네이티브 객체는 구조화 복제가 안 됩니다

★ 대응
  ① 워커 안에서 각자 만들기 (설정만 전달)
       workerData: { pattern: '\\d+' }
       워커 안에서: new native.Matcher(pattern)
  ② 순수 데이터만 주고받기 (Buffer · SharedArrayBuffer · j04)
  ③ 애초에 Rust 안에서 병렬화 (rayon · j05) ★ 대개 이게 낫습니다

★ 각 워커가 애드온을 로드하면
  · .node 는 프로세스당 한 번 로드되고 워커끼리 공유됩니다
  · 하지만 Rust 의 전역 상태(static)도 공유됩니다 ★
    → OnceLock · Mutex 로 보호해야 합니다 (r02 · ⚡ e06)
  · napi-rs 는 워커별 Env 를 구분해 줍니다

wrap 과 finalizer

#[napi] struct 가 만들어 내는 것

  ① JS 클래스를 정의 (napi_define_class)
  ② new 하면 JS 객체를 만들고
  ③ Rust 구조체를 Box 로 힙에 올린 뒤
  ④ napi_wrap 으로 JS 객체에 그 포인터를 붙입니다 ★
  ⑤ finalizer 를 등록 — GC 될 때 Box 를 해제

  JS 객체  ──wrap──▶  Box<Matcher> (Rust 힙)
     │
     └─ GC 되면 finalizer → drop(Box) → Drop::drop 호출

★ 그래서
  · 메서드 호출마다 napi_unwrap 으로 포인터를 꺼냅니다 (매우 쌈)
  · Rust 구조체는 JS 객체와 수명이 묶입니다
  · JS 가 참조를 놓으면 언젠가 해제됩니다 (시점은 GC 에 달림)

# 생성된 코드 확인
cargo expand --lib | grep -A 30 "impl.*Matcher"

메모리 누수 진단

// 인스턴스가 정말 해제되는지 확인
const v8 = require('v8')

function measure() {
  global.gc?.()                       // node --expose-gc
  return process.memoryUsage()
}

const before = measure()
for (let i = 0; i < 100_000; i++) {
  const m = new native.Matcher('\\d+')
  m.findAll('test')
}
const after = measure()
console.log('rss 증가', (after.rss - before.rss) / 1e6, 'MB')
// ★ 크게 늘면 Drop 이 안 불리거나 외부 메모리가 남는 것입니다

// 힙 스냅샷으로 JS 쪽 누수 확인
v8.writeHeapSnapshot('/tmp/heap.heapsnapshot')
// Chrome DevTools 에서 열어 보세요

// 네이티브 메모리 누수는
//   리눅스: valgrind --leak-check=full node app.js  (느립니다)
//   또는 jemalloc/tcmalloc 의 프로파일러
//   가장 확실한 것: Rust 쪽 단위 테스트에서 Drop 카운트 검증 (🔐 o07)

처음부터 끝까지

# ① 도구 설치 (한 번만)
cargo install wasm-pack
rustup target add wasm32-unknown-unknown

# ② 프로젝트
cargo new --lib fastwasm
cd fastwasm

# ③ 빌드 — 대상에 따라 --target 을 고릅니다 ★
wasm-pack build --target web       # <script type="module"> 로 직접
wasm-pack build --target bundler   # webpack · vite 등 번들러용
wasm-pack build --target nodejs    # Node 에서 require
wasm-pack build --release          # 최적화 ★ 크기가 크게 줄어듭니다

# 결과: pkg/
#   fastwasm_bg.wasm      실제 바이너리
#   fastwasm.js           글루 코드
#   fastwasm.d.ts         TypeScript 타입 ★
#   package.json          npm 배포 준비 완료

# Cargo.toml
[lib]
crate-type = ["cdylib", "rlib"]     # rlib 도 두면 cargo test 가 됩니다

[dependencies]
wasm-bindgen = "0.2"

[profile.release]
opt-level = "z"                     # 크기 우선 (j09)
lto = true

코드와 사용

// src/lib.rs
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn sum_squares(n: u32) -> u32 {
    (1..=n).map(|x| x * x).sum()
}

#[wasm_bindgen]
pub fn count_words(text: &str) -> usize {
    text.split_whitespace().count()
}

// 구조체도 클래스로 나갑니다
#[wasm_bindgen]
pub struct Counter { total: u32 }

#[wasm_bindgen]
impl Counter {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Counter { Counter { total: 0 } }
    pub fn increment(&mut self) -> u32 { self.total += 1; self.total }
    #[wasm_bindgen(getter)]
    pub fn total(&self) -> u32 { self.total }
}

// 브라우저 (--target web)
import init, { sum_squares, Counter } from './pkg/fastwasm.js'

await init()                          // ★ WASM 로드 (한 번)
console.log(sum_squares(1000))
const c = new Counter()
c.increment()

web-sys · js-sys

[dependencies]
wasm-bindgen = "0.2"
js-sys = "0.3"
web-sys = { version = "0.3", features = [
    "console", "Window", "Document", "HtmlCanvasElement",
    "CanvasRenderingContext2d", "Performance",
] }
console_error_panic_hook = "0.1"     # 패닉을 콘솔에 보이게 ★

use wasm_bindgen::prelude::*;
use web_sys::console;

#[wasm_bindgen(start)]
pub fn main() {
    console_error_panic_hook::set_once();     // ★ 반드시 넣으세요
    console::log_1(&"WASM 시작".into());
}

#[wasm_bindgen]
pub fn draw(canvas_id: &str) -> Result<(), JsValue> {
    let doc = web_sys::window().unwrap().document().unwrap();
    let canvas = doc.get_element_by_id(canvas_id).unwrap()
        .dyn_into::<web_sys::HtmlCanvasElement>()?;
    let ctx = canvas.get_context("2d")?.unwrap()
        .dyn_into::<web_sys::CanvasRenderingContext2d>()?;
    ctx.fill_rect(10.0, 10.0, 100.0, 50.0);
    Ok(())
}

// 임의의 JS 함수 부르기
#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = console)]
    fn log(s: &str);
    fn alert(s: &str);
    type MyClass;
    #[wasm_bindgen(method)]
    fn my_method(this: &MyClass, x: u32) -> u32;
}

비동기와 Promise

wasm-bindgen-futures = "0.4"

use wasm_bindgen_futures::JsFuture;

#[wasm_bindgen]
pub async fn fetch_json(url: String) -> Result<JsValue, JsValue> {
    let win = web_sys::window().unwrap();
    let resp = JsFuture::from(win.fetch_with_str(&url)).await?;
    let resp: web_sys::Response = resp.dyn_into()?;
    JsFuture::from(resp.json()?).await
}
// JS: const data = await fetch_json('/api')   ★ Promise 를 반환합니다

★ WASM 의 스레드 제약
  · 기본적으로 싱글 스레드입니다
  · rayon 을 쓰려면 wasm-bindgen-rayon + SharedArrayBuffer 가 필요하고,
    COOP/COEP 헤더를 서버에서 설정해야 합니다 (제약이 큽니다)
  · 대개는 Web Worker 에서 WASM 인스턴스를 여러 개 띄우는 편이 현실적입니다

★ 시간 측정
  std::time::Instant 는 WASM 에서 패닉합니다 ★
  → web_sys::window().performance().now() 를 쓰거나
    instant 크레이트(wasm 대응)를 쓰세요

WASM 은 숫자만 주고받습니다

WebAssembly 명세상 함수 인자는 i32 · i64 · f32 · f64 뿐입니다.
문자열도 객체도 없습니다.

그래서 wasm-bindgen 이 하는 일
  ① 문자열을 넘길 때
     JS 가 UTF-8 로 인코딩 → WASM 메모리에 복사 → (ptr, len) 을 전달
  ② 문자열을 받을 때
     WASM 이 (ptr, len) 반환 → JS 가 그 메모리를 읽어 문자열 생성
  ③ JS 객체를 넘길 때
     '핸들 테이블' 에 넣고 인덱스(i32)를 전달 ★
     Rust 의 JsValue 가 그 인덱스입니다

  → 생성되는 fastwasm.js 가 이 변환을 전부 담고 있습니다

# 글루 코드 읽어 보기
cat pkg/fastwasm.js | head -60

★ 성능 의미
  · 숫자 전달은 사실상 공짜
  · 문자열은 인코딩 + 복사 (짧아도 수백 ns)
  · JsValue 는 핸들 테이블 조회
  → 경계를 자주 넘지 말라는 원칙이 여기서도 같습니다 (j01)

WASM 바이너리 들여다보기

# 도구
cargo install wasm-tools
npm i -g wasm-opt        # binaryen

# 텍스트 형식으로
wasm-tools print pkg/fastwasm_bg.wasm | head -50

# 무엇을 내보내고 가져오나
wasm-tools print pkg/fastwasm_bg.wasm | grep -E "^\s*\(export|\(import"

# 섹션별 크기
wasm-tools objdump pkg/fastwasm_bg.wasm

# 검증
wasm-tools validate pkg/fastwasm_bg.wasm

# ★ 표준 명령 확인 — 어떤 WASM 기능을 쓰는지
#   SIMD · bulk-memory · reference-types 등을 쓰면
#   오래된 브라우저에서 로드가 실패합니다
wasm-tools print *.wasm | grep -c "v128"       # SIMD 사용 여부

# 타깃 기능 제한
#   RUSTFLAGS="-C target-feature=-simd128" cargo build --target wasm32-unknown-unknown

효과 순서대로 ★

# ① 릴리즈 빌드 (기본 중의 기본)
wasm-pack build --release

# ② Cargo.toml 프로파일 (🛠️ b06 · b10)
[profile.release]
opt-level = "z"        # 크기 우선 ("s" 는 절충, 3 은 속도 우선)
lto = true             # 링크 타임 최적화 ★ 효과가 큽니다
codegen-units = 1      # 더 느린 빌드, 더 작은 결과
panic = "abort"        # 패닉 언와인딩 코드 제거 ★
strip = true           # 심볼 제거

# ③ wasm-opt (binaryen) — wasm-pack 이 자동 실행합니다
[package.metadata.wasm-pack.profile.release]
wasm-opt = ["-Oz", "--enable-bulk-memory"]

# ④ 의존성 줄이기 — 가장 효과가 큰 경우가 많습니다
#    default-features = false 로 안 쓰는 기능 끄기 (🛠️ b04)
serde = { version = "1", default-features = false, features = ["derive"] }

# 결과 확인
ls -lh pkg/*.wasm
gzip -c pkg/*.wasm | wc -c        # ★ 실제 전송 크기는 압축 후입니다
brotli -c pkg/*.wasm | wc -c      # 브라우저는 보통 br 을 씁니다

무엇이 큰지 찾기 ★

# twiggy — 함수별 크기 분석
cargo install twiggy

twiggy top pkg/fastwasm_bg.wasm            # 큰 것부터
twiggy top -n 20 pkg/fastwasm_bg.wasm
twiggy dominators pkg/fastwasm_bg.wasm     # 무엇이 무엇을 끌고 오나 ★
twiggy paths pkg/fastwasm_bg.wasm 함수이름  # 왜 포함됐나

# 출력 예
#  Shallow Bytes │ Shallow % │ Item
# ───────────────┼───────────┼─────────────────────────
#         38 210 │    18.2 % │ core::fmt::… (포매팅)
#         21 044 │    10.0 % │ regex::…
#         12 803 │     6.1 % │ std::panicking::…

# ★ 자주 나오는 범인들
#   · core::fmt (format! · Display) — println! 을 지우면 크게 줍니다
#   · panic 메시지 문자열 — panic = "abort" + panic_immediate_abort
#   · regex · chrono · serde_json 같은 큰 크레이트
#   · 백트레이스 코드

Vite · webpack 설정

wasm-pack build --target bundler       # 번들러용으로 빌드

// vite.config.js
import wasm from 'vite-plugin-wasm'
import topLevelAwait from 'vite-plugin-top-level-await'

export default {
  plugins: [wasm(), topLevelAwait()],
  optimizeDeps: { exclude: ['fastwasm'] },     // ★ 사전 번들 제외
}

// webpack 5 — 실험적 기능을 켜야 합니다
module.exports = {
  experiments: { asyncWebAssembly: true },
}

★ 자주 겪는 문제
  · "Cannot use import statement outside a module"
      → --target 을 잘못 고른 것입니다 (j08)
  · WASM 이 base64 로 인라인돼 크기가 33% 커짐
      → 번들러 설정에서 asset 으로 내보내게 하세요
  · 개발 서버에서는 되는데 빌드하면 404
      → publicPath / base 설정 확인
  · Next.js
      → next.config.js 에서 experiments.asyncWebAssembly 설정

Node · 엣지에서 쓰기

// Node (--target nodejs)
const wasm = require('./pkg/fastwasm.js')
console.log(wasm.sum_squares(1000))     // init 불필요 (동기 로드)

// Cloudflare Workers
import wasmModule from './fastwasm_bg.wasm'
import * as bindings from './fastwasm_bg.js'
const instance = await WebAssembly.instantiate(wasmModule, {
  './fastwasm_bg.js': bindings
})
bindings.__wbg_set_wasm(instance.exports)

// Deno
import init, { sum_squares } from './pkg/fastwasm.js'
await init()

★ 엣지 런타임의 제약
  · Cloudflare Workers: WASM 모듈 크기 제한 (플랜에 따라 다름)
  · 시작 시간이 요금·지연에 직결됩니다 → 크기가 곧 비용 ★
  · 파일 시스템·스레드 없음 (j08 과 동일)

★ Node 에서 WASM vs 애드온 (j01)
  · 배포 단순성: WASM 압승 (파일 하나)
  · 성능: 애드온이 보통 우세하지만 격차는 작습니다
  · 라이브러리로 공개할 거면 WASM 을 먼저 고려하세요

SIMD 와 타깃 기능

# WASM SIMD (128비트) 켜기 — 수치 연산에서 효과가 큽니다
RUSTFLAGS="-C target-feature=+simd128" wasm-pack build --release

# 지원 확인 (브라우저)
#   WebAssembly.validate(새 SIMD 명령이 든 모듈)
#   또는 wasm-feature-detect 라이브러리

# ★ 두 벌 빌드 + 런타임 분기가 안전한 방법입니다
#   simd 버전과 기본 버전을 만들어 두고 감지해서 고릅니다

# 다른 유용한 기능
#   +bulk-memory      memcpy 가 빨라집니다 (기본 켜짐)
#   +mutable-globals
#   +reference-types

# 메모리 초기 크기 지정 (grow 를 줄이면 뷰 무효화도 줄어듭니다 · j08)
RUSTFLAGS="-C link-arg=--initial-memory=16777216" cargo build

할당자 교체와 no_std

# 기본 할당자(dlmalloc)는 코드가 큽니다
[dependencies]
wee_alloc = "0.4"          # 아주 작지만 느립니다 (유지보수 주의)
# 또는 talc · lol_alloc

#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

// ★ 트레이드오프
//   wee_alloc: 바이너리 ~10KB 절약, 할당 성능은 떨어집니다
//   할당이 잦은 코드라면 기본 할당자가 낫습니다 — 측정하세요 (⚡ e01)

// 진짜 작게 — 표준 라이브러리 없이
#![no_std]
extern crate alloc;
// 수 KB 까지 줄지만, 쓸 수 있는 것이 크게 제한됩니다.
// 대부분의 실무 코드에는 과합니다.

★ 크기 목표 감각 (참고용 — 코드에 따라 크게 다릅니다)
  hello world           ~ 수십 KB
  간단한 파싱 로직       ~ 100 KB
  regex 포함             ~ 300 KB+
  serde_json 포함        ~ 200 KB+
  이미지 처리(image 크레이트) ~ 1 MB+

  → gzip/brotli 로 보통 1/3 로 줄어듭니다.
    실제 전송 크기로 판단하세요.

배포 구조 ★

npm 에 올라가는 패키지들

  fastmod                        메인 (index.js + index.d.ts, 바이너리 없음)
  ├─ fastmod-linux-x64-gnu       optionalDependencies
  ├─ fastmod-linux-x64-musl
  ├─ fastmod-linux-arm64-gnu
  ├─ fastmod-darwin-x64
  ├─ fastmod-darwin-arm64
  └─ fastmod-win32-x64-msvc

★ 동작
  npm install fastmod
    → npm 이 os/cpu 필드를 보고 '내 플랫폼 것만' 설치합니다
    → index.js 가 그것을 require 합니다 (j02)
    → 다른 플랫폼 패키지는 optional 이라 실패해도 무시됩니다

// fastmod-linux-x64-gnu/package.json
{
  "name": "fastmod-linux-x64-gnu",
  "version": "0.1.0",
  "os": ["linux"],
  "cpu": ["x64"],
  "libc": ["glibc"],
  "main": "fastmod.linux-x64-gnu.node",
  "files": ["fastmod.linux-x64-gnu.node"]
}

CI 로 전부 만들기

# napi-rs 가 워크플로를 생성해 줍니다
npx @napi-rs/cli create-npm-dirs      # 서브 패키지 폴더 생성
# .github/workflows/CI.yml 은 create napi 가 이미 만들어 뒀습니다

# 흐름
#   ① 플랫폼별 job 에서 napi build --platform --release
#   ② 아티팩트 업로드
#   ③ 마지막 job 에서 전부 내려받아
#      napi artifacts     — .node 를 각 npm 폴더로 배치
#      napi prepublish    — package.json 들을 갱신
#      npm publish        — 서브 패키지 + 메인 패키지

★ 빌드 방법 (플랫폼별)
  linux x64 gnu       ubuntu 러너에서 그대로
  linux x64 musl      alpine 컨테이너 또는 zig 링커 ★
  linux arm64         cross · zigbuild · ARM 러너 (🛠️ b07)
  darwin x64/arm64    macos 러너 (둘 다 빌드 가능)
  win32 x64           windows 러너

  → napi-rs 의 기본 워크플로가 이걸 전부 담고 있습니다.
    처음에는 필요한 플랫폼만 남기고 줄이세요 (CI 시간 절약)

배포 전 확인 ★

□ 필요한 플랫폼을 전부 빌드했는가
    최소: linux-x64-gnu · linux-x64-musl · darwin-arm64 · win32-x64
□ 실제로 설치해 봤는가 (각 플랫폼에서)
    docker run --rm -it node:20-alpine sh -c "npm i fastmod && node -e '...'"
□ index.d.ts 가 패키지에 들어갔는가
    npm pack --dry-run 으로 파일 목록 확인 ★
□ files 필드에 필요한 것만 있는가 (src/ · target/ 제외)
□ 버전이 서브 패키지와 일치하는가
□ engines.node 가 N-API 버전과 맞는가
□ 바이너리 크기가 합리적인가 (🛠️ b10)
    strip = "symbols" · lto = true
□ 라이선스 파일이 포함됐는가
□ 첫 배포는 npm publish --tag next 로 미리 검증 ★

설치 검증 스크립트

#!/usr/bin/env bash
# scripts/verify-install.sh — 여러 환경에서 실제 설치 테스트
set -e

for img in node:20 node:20-alpine node:18; do
  echo "=== $img ==="
  docker run --rm "$img" sh -c "
    npm i -g fastmod@latest &&
    node -e \"const f=require('fastmod'); console.log(f.sumSquares(10))\"
  "
done

# arm64 도 (도커 buildx / QEMU)
docker run --rm --platform linux/arm64 node:20 sh -c "npm i fastmod && ..."

★ CI 에 넣으세요 (🛠️ b08)
  배포 job 다음에 '설치 검증' job 을 두고,
  실패하면 npm dist-tag 로 되돌립니다
    npm dist-tag add fastmod@0.9.0 latest

★ 되돌릴 수 있게
  · npm unpublish 는 24시간 제한이 있고 권장되지 않습니다
  · 대신 패치 버전을 올려 다시 배포하는 것이 정석입니다
  · deprecate 로 경고를 남길 수 있습니다
      npm deprecate fastmod@1.0.1 "설치 문제가 있습니다. 1.0.2 를 쓰세요"

크기 줄이기 (🛠️ b10 과 같은 기법)

[profile.release]
opt-level = 3          # 애드온은 보통 속도 우선 (WASM 과 다릅니다)
lto = "fat"
codegen-units = 1
strip = "symbols"      # ★ 심볼 제거 — 크기가 크게 줍니다
panic = "abort"        # 애드온에서도 대체로 안전합니다
                       # (단, 패닉이 프로세스를 죽입니다 — j03 의 에러 처리를 철저히)

# 확인
ls -lh *.node
cargo bloat --release --crates          # 어느 크레이트가 큰지 ★
cargo bloat --release -n 20             # 어느 함수가 큰지

# npm 패키지 크기
npm pack --dry-run
npx package-size fastmod

# ★ 실무 감각
#   .node 파일이 수 MB 면 사용자가 체감합니다.
#   특히 CI 에서 매번 내려받는 경우 (수천 번/일) 비용이 됩니다.

공급망 신뢰 ★

네이티브 바이너리를 배포한다는 것은
사용자 머신에서 임의 코드를 실행한다는 뜻입니다.
그래서 신뢰 장치가 중요합니다.

□ CI 에서만 배포 (로컬에서 npm publish 금지)
    npm 의 Trusted Publishing / provenance 를 켜세요
      npm publish --provenance
    → npm 페이지에 '어느 워크플로에서 빌드됐는지' 가 표시됩니다 ★

□ 2FA 를 켜기 (npm 계정 · 자동화 토큰은 최소 권한)

□ 재현 가능한 빌드에 가깝게
    rust-toolchain.toml 로 컴파일러 고정 (r01)
    Cargo.lock 커밋 (🛠️ b03)

□ 의존성 감사
    cargo audit · cargo deny (🛠️ b09)
    npm audit

□ 서브 패키지도 같은 조직/계정에서 배포
    이름 선점(typosquatting) 방지를 위해 미리 확보해 두세요

★ 사용자 입장의 검증
  npm 페이지의 provenance 배지 확인
  또는 소스에서 직접 빌드 (cargo build --release)

ABI 란 무엇인가

API — 소스 코드 수준의 약속 (함수 이름 · 인자 타입)
ABI — 기계어 수준의 약속 ★
        · 인자를 어느 레지스터·스택에 놓는가
        · 반환값은 어디로 오는가
        · 구조체 필드가 메모리에 어떻게 배치되는가
        · 함수 이름이 심볼로 어떻게 적히는가
        · 누가 스택을 정리하는가

C ABI 는 이것들이 '플랫폼마다 고정' 돼 있습니다.
  x86-64 SysV (리눅스·맥)  ·  Win64 (윈도우)  ·  AAPCS64 (ARM)

★ 그래서 C 로 컴파일된 라이브러리는
  어떤 언어에서도 부를 수 있습니다.
  Rust 는 "C 처럼 보이는 함수"를 만들 수 있습니다.

언제 C ABI 를 고르나 ★

★ C ABI 의 대가
  · Option · Result · String · Vec 을 못 씁니다 (f03 · f06)
  · 메모리 해제 책임을 문서로 정해야 합니다 (f06)
  · 패닉이 경계를 넘으면 안 됩니다 (f09)
  · 제네릭·트레이트가 사라집니다 (구체 함수만)
  · 컴파일러가 지켜 주던 것을 사람이 지켜야 합니다 ★

★ 그럼에도 얻는 것
  · 하나의 .so/.dll/.dylib 로 모든 언어 지원
  · 언어별 바인딩 코드를 각 언어에서 얇게 작성
  · 버전을 오래 유지할 수 있습니다 (안정된 인터페이스)

API 를 좁히는 방법

// ❌ Rust 내부 구조를 그대로 노출
#[no_mangle] pub extern "C" fn get_config() -> *const Config;
#[no_mangle] pub extern "C" fn config_get_host(c: *const Config) -> *const c_char;
#[no_mangle] pub extern "C" fn config_get_port(c: *const Config) -> u16;
// … 필드가 늘 때마다 함수가 늘어납니다

// ✅ '하려는 일' 단위로
#[no_mangle] pub extern "C" fn mylib_open(path: *const c_char) -> *mut Handle;
#[no_mangle] pub extern "C" fn mylib_process(h: *mut Handle,
                                             input: *const u8, in_len: usize,
                                             out: *mut u8, out_cap: usize,
                                             out_len: *mut usize) -> i32;
#[no_mangle] pub extern "C" fn mylib_close(h: *mut Handle);
#[no_mangle] pub extern "C" fn mylib_last_error(buf: *mut c_char, cap: usize) -> usize;
#[no_mangle] pub extern "C" fn mylib_version() -> u32;

// ★ 다섯 개면 충분한 경우가 많습니다.
//   설정은 JSON 문자열 하나로 받으면 구조체 ABI 문제도 사라집니다 ★
#[no_mangle] pub extern "C" fn mylib_configure(json: *const c_char) -> i32;

크레이트 설정

[lib]
name = "mylib"
crate-type = ["cdylib", "staticlib", "rlib"]
#              ^^^^^^   ^^^^^^^^^^   ^^^^
#   cdylib    .so/.dll/.dylib — 동적 링크 (대부분 이것) ★
#   staticlib .a/.lib — C/C++ 앱에 정적으로 넣을 때
#   rlib      Rust 크레이트로도 쓰기 (cargo test 를 위해 두면 편합니다)

[dependencies]
libc = "0.2"                  # c_char · c_void 등

[build-dependencies]
cbindgen = "0.27"             # 헤더 자동 생성 (f04)

[profile.release]
lto = true
strip = "symbols"             # ★ 내부 심볼 감추기 (🛠️ b10)

cargo build --release
ls target/release/
#   libmylib.so     (리눅스)
#   libmylib.dylib  (맥)
#   mylib.dll       (윈도우) + mylib.dll.lib
#   libmylib.a      (staticlib)

extern "C" 가 지정하는 것

extern "C" fn f(a: i32, b: i32) -> i32 { a + b }

// x86-64 SysV (리눅스·맥) 에서
//   a → edi,  b → esi,  반환 → eax
//   호출자가 스택을 정리
//
// Win64 에서
//   a → ecx,  b → edx,  반환 → eax
//   섀도 스페이스 32바이트 필요
//
// → extern "C" 는 "그 플랫폼의 C 규약을 따르라" 는 뜻입니다.
//   플랫폼별 차이는 컴파일러가 처리합니다. ★

// 다른 규약들 (특수한 경우)
extern "system" fn g();     // 윈도우 API (Win32 에서는 stdcall)
extern "stdcall" fn h();    // 32비트 윈도우 레거시
extern "Rust" fn i();       // 기본값 (불안정 · 🔬 d11)

// 확인
//   objdump -d target/release/libmylib.so | grep -A 20 "<mylib_process>:"

런타임이 없다는 이점

Rust 가 C ABI 라이브러리로 특히 좋은 이유

  · GC 가 없습니다 — 초기화·정지 시간이 없습니다
  · 런타임 초기화가 필요 없습니다 (Go 는 런타임을 띄워야 합니다)
  · 예외 테이블 외에는 숨은 비용이 없습니다
  · 정적 링크가 자연스럽습니다 (musl 로 완전 정적도 가능 · 🛠️ b07)

★ 비교
  C/C++   같은 수준. 대신 메모리 안전은 사람이 책임
  Go      cgo 경계 비용이 크고 런타임이 따라옵니다
  C#/자바 런타임(CLR/JVM)을 임베드해야 합니다
  Rust    C 와 같은 비용 + 안전한 내부 ★

★ 남는 의존성 확인
  ldd target/release/libmylib.so
    linux-vdso · libgcc_s · libc · libm 정도

  완전 정적으로 (musl)
    rustup target add x86_64-unknown-linux-musl
    cargo build --release --target x86_64-unknown-linux-musl

최소 예제

// src/lib.rs
#[no_mangle]
pub extern "C" fn mylib_add(a: i32, b: i32) -> i32 {
    a + b
}

// #[no_mangle]  이름을 그대로 심볼로 (안 붙이면 _ZN5mylib3add17h... 가 됩니다)
// extern "C"    C 호출 규약
// pub           크레이트 밖으로

// 2024 에디션부터는 unsafe 표기를 씁니다
// #[unsafe(no_mangle)]
// pub unsafe extern "C" fn mylib_add(a: i32, b: i32) -> i32 { a + b }

cargo build --release

# 심볼 확인 ★ 문제가 생기면 항상 여기부터
nm -D target/release/libmylib.so | grep mylib
#   0000000000007a10 T mylib_add        ← T = 텍스트(코드), 전역

# 윈도우
dumpbin /exports target\release\mylib.dll

# 맥
nm -gU target/release/libmylib.dylib | grep mylib

쓸 수 있는 타입 ★

// ❌ 절대 쓰면 안 되는 것들 (ABI 가 정의되지 않음)
// pub extern "C" fn bad() -> String;          // Rust 전용 레이아웃
// pub extern "C" fn bad2() -> Vec<u8>;
// pub extern "C" fn bad3() -> Result<i32, E>;
// pub extern "C" fn bad4(s: &str);            // 팻 포인터 (🔐 o04)
// pub extern "C" fn bad5<T>(x: T);            // 제네릭

// ✅ 대신
//   String  → *mut c_char + 해제 함수 (f06)
//   Vec<u8> → *mut u8 + len 또는 출력 버퍼
//   Result  → 에러 코드 i32 (f09)
//   &str    → *const u8 + usize
//   bool 은 Rust 와 C99 모두 1바이트라 안전합니다 ★

// clippy 가 잡아 줍니다
//   cargo clippy -- -W clippy::not_unsafe_ptr_arg_deref

"symbol not found" 진단 순서 ★

# ① 심볼이 정말 있나
nm -D libmylib.so | grep mylib_add
#   비어 있으면 → #[no_mangle] 을 빠뜨렸거나 pub 이 아님

# ② 이름이 정확한가 (오타 · 접두사)
nm -D libmylib.so | grep -i add

# ③ 맥/윈도우의 언더스코어
#   맥: C 심볼 앞에 _ 가 붙습니다 (nm 출력에는 보이지만 dlsym 은 그대로)
#   윈도우 32비트 stdcall: _name@8 형태

# ④ 라이브러리를 정말 로드했나
LD_DEBUG=libs python -c "import ctypes; ctypes.CDLL('./libmylib.so')"

# ⑤ 아키텍처가 맞나
file libmylib.so
#   ELF 64-bit ... x86-64        ← 32비트 파이썬이면 로드 실패

# ⑥ 의존 라이브러리가 있나
ldd libmylib.so | grep "not found"

# ⑦ 최적화로 지워졌나 — 안 쓰이는 함수를 링커가 제거할 수 있습니다
#    #[no_mangle] pub 이면 보통 남지만, LTO 설정에 따라 다릅니다
#    확실히 하려면 #[used] 나 링커 스크립트를 쓰세요

심볼 가시성 제어

기본적으로 cdylib 은 #[no_mangle] pub 함수만 내보냅니다.
하지만 정적 링크한 C 라이브러리의 심볼이 함께 새어 나갈 수 있습니다 (f08).

★ 왜 문제인가
  같은 프로세스에 다른 버전의 같은 라이브러리가 있으면
  심볼이 충돌해 엉뚱한 함수가 불릴 수 있습니다.
  (파이썬에서 여러 확장이 각자 libz 를 정적 링크한 경우 등)

★ 대응
  # 리눅스 — 버전 스크립트로 내보낼 심볼을 지정
  # mylib.map
  { global: mylib_*; local: *; };
  # .cargo/config.toml
  # rustflags = ["-C", "link-arg=-Wl,--version-script=mylib.map"]

  # 맥 — 내보내기 목록
  # -Wl,-exported_symbols_list,exported.txt

  # 확인
  nm -D libmylib.so | grep " T " | wc -l      # 내보내는 심볼 개수 ★

이름이 어떻게 바뀌나

# Rust 는 이름에 크레이트·모듈·타입 해시를 넣습니다 (같은 이름 허용을 위해)
nm target/release/libmylib.rlib | grep add
#   _ZN5mylib5inner3add17h8f3a2c1b9e4d5f6aE

# 디맹글
rustfilt <<< "_ZN5mylib5inner3add17h8f3a2c1b9e4d5f6aE"
#   mylib::inner::add::h8f3a2c1b9e4d5f6a

# C++ 도 맹글합니다 (오버로딩 때문)
c++filt <<< "_Z3addii"
#   add(int, int)

# ★ #[no_mangle] 은 "그냥 mylib_add 로 적어라" 는 지시입니다.
#   그래서 오버로딩이 불가능하고, 이름 충돌도 직접 피해야 합니다.

# 부분적 대안 — export_name 으로 이름 지정
#[export_name = "mylib_v2_add"]
pub extern "C" fn add_v2(a: i32, b: i32) -> i32 { a + b }
# 버전을 이름에 넣는 기법입니다 (f09)

동적 링크가 실제로 하는 일

dlopen("libmylib.so") 이 하는 일
  ① 파일을 메모리에 매핑
  ② 의존 라이브러리를 재귀적으로 로드 (ldd 로 보이는 것들)
  ③ 재배치(relocation) — 절대 주소를 채움
  ④ 초기화 함수 실행 (.init_array)

dlsym("mylib_add")
  ⑤ 심볼 테이블에서 찾아 함수 주소를 반환

★ 실무에서 만나는 것들
  · RTLD_GLOBAL vs RTLD_LOCAL — 심볼을 전역에 공개할지
    파이썬은 기본 LOCAL 이라 확장끼리 심볼이 안 섞입니다 ★
  · LD_LIBRARY_PATH / DYLD_LIBRARY_PATH / PATH(윈도우)
  · rpath — 라이브러리 안에 검색 경로를 박아 둠
      cargo: rustflags = ["-C", "link-arg=-Wl,-rpath,$ORIGIN"]
  · 지연 바인딩 — 처음 호출할 때 주소를 해결 (LD_BIND_NOW 로 끄기)

# 로드 과정 추적
LD_DEBUG=all ./app 2>&1 | head -50
strace -e trace=openat ./app

무슨 일이 일어나나

struct Bad { a: u8, b: u64, c: u8 }
#[repr(C)]
struct Good { a: u8, b: u64, c: u8 }

println!("{} {}", size_of::<Bad>(), size_of::<Good>());   // 16  24

// Bad 의 실제 배치 (컴파일러가 재배치)
//   [b: 8바이트][a: 1][c: 1][패딩 6]  = 16
// Good 의 배치 (C 규칙 그대로)
//   [a: 1][패딩 7][b: 8][c: 1][패딩 7] = 24

// ★ C 쪽에서 Bad 를 { uint8_t a; uint64_t b; uint8_t c; } 로 선언하면
//   a 를 읽었는데 b 의 하위 바이트가 나옵니다 — 크래시 없이 값만 틀립니다

#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct Point { pub x: f64, pub y: f64 }

#[no_mangle]
pub extern "C" fn mylib_distance(a: Point, b: Point) -> f64 {
    ((a.x - b.x).powi(2) + (a.y - b.y).powi(2)).sqrt()
}

/* C 쪽 */
typedef struct { double x, y; } Point;
double mylib_distance(Point a, Point b);

repr 의 종류 ★

// transparent — 뉴타입을 C 에 그대로 (r07)
#[repr(transparent)]
pub struct Handle(*mut c_void);      // C 에서는 그냥 void*

// C 스타일 enum
#[repr(i32)]
pub enum Status { Ok = 0, NotFound = 1, Error = 2 }

// packed — 네트워크 프로토콜 등
#[repr(C, packed)]
struct Header { kind: u8, len: u32 }   // 5바이트 (패딩 없음)
// ❗ packed 필드의 참조를 만들면 UB 입니다 (정렬 위반 · 🔬 d03)
//    let r = &h.len;                  // ❌ 컴파일러가 막습니다
let len = h.len;                        // ✅ 복사해서 쓰기
let len = std::ptr::addr_of!(h.len);    // ✅ 주소만 필요하면

// 정렬 강제 — false sharing 방지 (⚡ e06)
#[repr(align(64))]
struct CacheAligned(AtomicU64);

크기·오프셋을 검증하세요 ★

use std::mem::{size_of, align_of, offset_of};

// 컴파일 타임 검증 — 배치가 바뀌면 빌드가 실패합니다 ★
const _: () = {
    assert!(size_of::<Header>() == 16);
    assert!(align_of::<Header>() == 8);
    assert!(offset_of!(Header, kind) == 0);
    assert!(offset_of!(Header, len) == 8);
};

#[test]
fn layout_is_stable() {
    assert_eq!(size_of::<Point>(), 16);
    assert_eq!(size_of::<Status>(), 4);
    assert_eq!(size_of::<Handle>(), size_of::<*mut c_void>());
}

// ★ 왜 중요한가
//   필드를 하나 추가하면 크기가 바뀌고, 이미 배포된 다른 언어의
//   바인딩이 전부 깨집니다. 그것도 조용히 (f09)
//   이 테스트가 있으면 '의도한 변경'인지 리뷰에서 드러납니다.

// C 헤더와 대조하려면 (f04 의 cbindgen 이 대개 해결)
//   빌드에서 헤더를 생성하고, C 컴파일러로 static_assert 를 돌리는
//   테스트를 두는 팀도 있습니다

플랫폼별 차이 주의

★ 플랫폼마다 다른 것들
  · usize / size_t         64비트: 8, 32비트·wasm32: 4 ★
  · long                   리눅스 64: 8, 윈도우 64: 4 ★★ 가장 흔한 함정
  · c_char                 x86: signed, ARM: unsigned
  · 구조체 정렬            대체로 같지만 ARM32 등에서 다를 수 있음
  · 엔디안                 대부분 리틀엔디안이지만 명시하는 것이 안전

★ 대응
  · 고정 크기 타입만 쓰세요: i32 · u64 · f64 ★
    long · int 를 인터페이스에 두지 마세요
  · 크기가 필요하면 u64 로 통일 (usize 대신)
  · 바이트 순서는 문서에 명시하고, 필요하면 to_le_bytes (🔐 o04)

// C 타입이 필요하면 libc 를 쓰세요 (플랫폼별로 올바르게 정의됨)
use libc::{c_int, c_long, c_char, size_t};

// 검증
#[test]
fn no_platform_dependent_types() {
    // 인터페이스 구조체에 usize 가 없는지 리뷰 항목으로 두세요
}

도구

# Rust 쪽 — 타입 크기 전부 출력
cargo +nightly rustc --release -- -Zprint-type-sizes | grep -A 5 "Header"

# C 쪽 — 헤더의 배치 확인
cat > t.c <<'EOF'
#include <stdio.h>
#include <stddef.h>
#include "mylib.h"
int main(void) {
    printf("size=%zu align=%zu\n", sizeof(Header), _Alignof(Header));
    printf("kind@%zu len@%zu\n", offsetof(Header, kind), offsetof(Header, len));
    return 0;
}
EOF
gcc t.c -o t && ./t

# 파이썬 ctypes 쪽 (f05)
python -c "
import ctypes
class Header(ctypes.Structure):
    _fields_ = [('kind', ctypes.c_uint8), ('len', ctypes.c_uint32)]
print(ctypes.sizeof(Header))
print(Header.len.offset)"

# ★ 세 곳의 숫자가 같아야 합니다. 다르면 그 자리가 버그입니다.

바이트를 직접 들여다보기

// 구조체의 실제 바이트를 덤프해 보기 (디버깅용)
fn dump<T>(v: &T) {
    let p = v as *const T as *const u8;
    let bytes = unsafe { std::slice::from_raw_parts(p, size_of::<T>()) };
    for (i, b) in bytes.iter().enumerate() {
        if i % 8 == 0 { print!("\n{i:04x}: "); }
        print!("{b:02x} ");
    }
    println!();
}

let h = Header { kind: 1, len: 0x1234 };
dump(&h);
// 0000: 01 00 00 00 34 12 00 00     ← 패딩과 리틀엔디안이 보입니다 ★

// 안전한 대안 — bytemuck 크레이트
// #[derive(bytemuck::Pod, bytemuck::Zeroable)]
// #[repr(C)]
// struct Header { kind: u32, len: u32 }
// let bytes: &[u8] = bytemuck::bytes_of(&h);     // ✅ unsafe 없이

// zerocopy 크레이트도 같은 목적입니다
//   바이트 ↔ 구조체 변환을 컴파일 타임에 검증합니다 (🔬 d08)

붙이는 방법

# Cargo.toml
[build-dependencies]
cbindgen = "0.27"

// build.rs
fn main() {
    let crate_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
    let out = std::path::Path::new(&crate_dir).join("include/mylib.h");
    std::fs::create_dir_all(out.parent().unwrap()).unwrap();

    cbindgen::generate(&crate_dir)
        .expect("cbindgen 실패")
        .write_to_file(&out);

    println!("cargo:rerun-if-changed=src/ffi.rs");   // ★ 바뀔 때만 재생성
}

# cbindgen.toml
language = "C"                 # 또는 "C++"
include_guard = "MYLIB_H"
autogen_warning = "/* 자동 생성 파일입니다. 고치지 마세요. */"
header = "/* mylib - MIT License */"
cpp_compat = true              # C++ 에서도 쓰이게 extern "C" 를 감쌉니다 ★

[export]
prefix = ""
include = ["Point", "Status", "Handle"]    # 내보낼 타입을 명시
exclude = ["Internal"]

[enum]
prefix_with_name = true        # Status_Ok 형태로 (C 이름 충돌 방지)

[parse]
parse_deps = false

생성 결과

// src/ffi.rs
#[repr(C)]
pub struct Point { pub x: f64, pub y: f64 }

#[repr(i32)]
pub enum Status { Ok = 0, NotFound = 1 }

/// 두 점 사이의 거리를 구합니다.
#[no_mangle]
pub extern "C" fn mylib_distance(a: Point, b: Point) -> f64 { }

/// 핸들을 엽니다. 실패하면 NULL 을 반환합니다.
#[no_mangle]
pub extern "C" fn mylib_open(path: *const c_char) -> *mut Handle { }

/* include/mylib.h — 자동 생성 */
#ifndef MYLIB_H
#define MYLIB_H

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

typedef enum Status { Status_Ok = 0, Status_NotFound = 1 } Status;
typedef struct Handle Handle;          /* 불투명 타입 ★ */
typedef struct Point { double x; double y; } Point;

#ifdef __cplusplus
extern "C" {
#endif

/* 두 점 사이의 거리를 구합니다. */
double mylib_distance(Point a, Point b);

/* 핸들을 엽니다. 실패하면 NULL 을 반환합니다. */
struct Handle *mylib_open(const char *path);

#ifdef __cplusplus
}
#endif
#endif /* MYLIB_H */

배포에 담을 것

배포 아티팩트 (플랫폼별)
  include/mylib.h              헤더 (플랫폼 무관)
  lib/libmylib.so              리눅스 동적
  lib/libmylib.a               리눅스 정적
  lib/mylib.dll + mylib.lib    윈도우
  lib/libmylib.dylib           맥
  mylib.pc                     pkg-config 파일 ★
  LICENSE · README

# pkg-config 파일 예 (C 개발자가 편해집니다)
prefix=/usr/local
libdir=${prefix}/lib
includedir=${prefix}/include

Name: mylib
Description: 빠른 텍스트 처리
Version: 1.2.0
Libs: -L${libdir} -lmylib
Cflags: -I${includedir}

# 쓰는 쪽
gcc app.c $(pkg-config --cflags --libs mylib) -o app

버전 정보를 헤더에 넣기

// 컴파일 타임 상수는 cbindgen 이 #define 으로 내보냅니다
pub const MYLIB_VERSION_MAJOR: u32 = 1;
pub const MYLIB_VERSION_MINOR: u32 = 2;

// 런타임 확인 함수도 함께 (f09)
#[no_mangle]
pub extern "C" fn mylib_version() -> u32 {
    (MYLIB_VERSION_MAJOR << 16) | MYLIB_VERSION_MINOR
}

#[no_mangle]
pub extern "C" fn mylib_version_string() -> *const c_char {
    concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr() as *const c_char
}
// ★ 문자열 리터럴에 \0 을 붙이면 해제가 필요 없는 정적 C 문자열이 됩니다 (f06)

/* 쓰는 쪽에서 헤더와 라이브러리 버전이 맞는지 확인 */
if ((mylib_version() >> 16) != MYLIB_VERSION_MAJOR) {
    fprintf(stderr, "헤더와 라이브러리 버전 불일치\n");
    return 1;
}

표현 못 하는 것들

// ① 제네릭 — 구체화한 타입만 내보낼 수 있습니다
// pub struct Wrapper<T>(T);                  // ❌ 헤더에 안 나옴
#[repr(C)] pub struct WrapperU32 { inner: u32 }  // ✅ 구체 타입으로

// ② 트레이트 객체 · 클로저 — 불가능
//    → 함수 포인터 + user data 로 (f07)

// ③ 라이프타임이 있는 타입 — 무시됩니다
//    → 소유권 규약을 문서로 (f06)

// ④ 매크로로 생성한 항목 — parse 설정에 따라 놓칠 수 있습니다
//    → [parse] expand = ["mycrate"] 로 매크로 확장 후 파싱 (느립니다)

// ⑤ 의존 크레이트의 타입
//    [parse] parse_deps = true, include = ["othercrate"]

// 수동 보완 — 헤더에 직접 넣을 코드
// cbindgen.toml
//   after_includes = """
//   #define MYLIB_MAX_SIZE 4096
//   typedef void (*MylibLogFn)(const char *msg);
//   """

C++ 를 위한 배려

# cbindgen.toml
language = "C++"               # C++ 헤더로 생성
namespace = "mylib"            # 네임스페이스로 감싸기
[enum]
enum_class = true              # enum class 로 (타입 안전)

// C++ 사용자를 위한 RAII 래퍼를 함께 제공하면 친절합니다
namespace mylib {
class Handle {
public:
    explicit Handle(const char* path) : h_(mylib_open(path)) {
        if (!h_) throw std::runtime_error(last_error());
    }
    ~Handle() { if (h_) mylib_close(h_); }
    Handle(Handle&& o) noexcept : h_(o.h_) { o.h_ = nullptr; }
    Handle(const Handle&) = delete;

    std::vector<uint8_t> process(std::span<const uint8_t> in);
private:
    ::Handle* h_;
};
}
// ★ C ABI 는 최소 공통분모이고, 각 언어에서 그 언어다운 래퍼를 씌우는 것이
//   이 방식의 정석입니다 (🐍 y02 · 🟨 j06 과 같은 원칙)

가장 짧은 예제

// src/lib.rs
#[no_mangle]
pub extern "C" fn mylib_add(a: i32, b: i32) -> i32 { a + b }

#[no_mangle]
pub unsafe extern "C" fn mylib_sum(p: *const f64, n: usize) -> f64 {
    if p.is_null() || n == 0 { return 0.0; }
    std::slice::from_raw_parts(p, n).iter().sum()
}

import ctypes, sys, pathlib

# 플랫폼별 파일 이름
name = {"linux": "libmylib.so", "darwin": "libmylib.dylib",
        "win32": "mylib.dll"}[sys.platform]
lib = ctypes.CDLL(str(pathlib.Path("target/release") / name))

# ★ 반드시 시그니처를 지정하세요 (안 하면 int 로 가정합니다)
lib.mylib_add.argtypes = [ctypes.c_int32, ctypes.c_int32]
lib.mylib_add.restype  = ctypes.c_int32

lib.mylib_sum.argtypes = [ctypes.POINTER(ctypes.c_double), ctypes.c_size_t]
lib.mylib_sum.restype  = ctypes.c_double

print(lib.mylib_add(1, 2))          # 3

# numpy 배열을 그대로 넘기기 — 복사 없음 ★
import numpy as np
a = np.random.random(1_000_000)
ptr = a.ctypes.data_as(ctypes.POINTER(ctypes.c_double))
print(lib.mylib_sum(ptr, a.size))

타입 대응표 ★

# 구조체 (f03 과 배치가 일치해야 합니다)
class Point(ctypes.Structure):
    _fields_ = [("x", ctypes.c_double), ("y", ctypes.c_double)]

lib.mylib_distance.argtypes = [Point, Point]
lib.mylib_distance.restype  = ctypes.c_double
print(lib.mylib_distance(Point(0, 0), Point(3, 4)))    # 5.0

# ★ 검증 습관
assert ctypes.sizeof(Point) == 16      # Rust 쪽 assert 와 대조 (f03)

# 문자열
lib.mylib_count_words.argtypes = [ctypes.c_char_p]
lib.mylib_count_words.restype  = ctypes.c_size_t
lib.mylib_count_words("안녕 세상".encode("utf-8"))    # bytes 로 넘깁니다 ★

고르는 기준 ★

★ 판단
  · 파이썬만 쓰고 성능이 중요        → PyO3 (🐍 y02)
  · 여러 언어에서 공유해야 함        → C ABI + ctypes
  · 이미 있는 .so 를 잠깐 써 보기    → ctypes ★
  · 호출이 잦고 데이터가 작음        → PyO3 (ctypes 는 호출 비용이 큽니다)
  · C 라이브러리 래핑                → cffi 또는 bindgen (f08)

★ ctypes 호출 비용
  파이썬에서 인자를 변환하고 FFI 를 거치므로
  PyO3 보다 눈에 띄게 비쌉니다 (보통 수 배 · 직접 재 보세요 · ⚡ e01)
  → 루프에서 수백만 번 부르면 차이가 큽니다. 배치로 묶으세요 (🐍 y01)

★ ctypes 의 숨은 이점
  ctypes 는 호출 중 GIL 을 자동으로 놓습니다 ★
  → 긴 계산이라면 다른 파이썬 스레드가 그동안 돕니다 (🐍 y07)

라이브러리를 찾는 방법

import ctypes, ctypes.util, sys, pathlib

# ① 패키지 안에 함께 배포 (권장) ★
here = pathlib.Path(__file__).parent
name = {"linux": "libmylib.so", "darwin": "libmylib.dylib",
        "win32": "mylib.dll"}[sys.platform]
lib = ctypes.CDLL(str(here / name))

# ② 시스템에서 찾기
path = ctypes.util.find_library("mylib")
lib = ctypes.CDLL(path)

# ③ 환경 변수로 재정의 가능하게
import os
lib = ctypes.CDLL(os.getenv("MYLIB_PATH", str(here / name)))

# 윈도우 주의 ★
#   · CDLL 은 cdecl, WinDLL 은 stdcall — extern "C" 면 CDLL
#   · 파이썬 3.8+ 는 DLL 검색 경로가 제한됩니다
os.add_dll_directory(str(here))          # 의존 DLL 이 있을 때 필요

# 진단
#   리눅스: LD_DEBUG=libs python app.py
#   맥: DYLD_PRINT_LIBRARIES=1
#   윈도우: Dependencies.exe 또는 Process Monitor

파이썬 함수를 콜백으로 넘기기 (f07)

CALLBACK = ctypes.CFUNCTYPE(None, ctypes.c_float, ctypes.c_void_p)
#                           반환    인자1          인자2

lib.mylib_process.argtypes = [ctypes.c_char_p, CALLBACK, ctypes.c_void_p]

def on_progress(p, user):
    print(f"{p*100:.0f}%")

cb = CALLBACK(on_progress)        # ★ 반드시 변수에 보관하세요
lib.mylib_process(b"data", cb, None)

# ❗ 가장 흔한 크래시 원인
#   lib.mylib_process(b"data", CALLBACK(on_progress), None)
#   → 임시 객체가 즉시 GC 되어 함수 포인터가 무효가 됩니다 ★
#   반드시 파이썬 쪽에서 참조를 살려 두세요 (전역이나 인스턴스 필드에)

# 콜백 안에서 예외가 나면?
#   ctypes 가 stderr 에 출력하고 무시합니다 (C 로 전파되지 않습니다)
#   → 콜백 안을 try/except 로 감싸고 플래그로 알리세요

메모리 수명 주의 ★

# ❌ 임시 객체의 포인터를 넘기기
lib.process(bytes(data))            # 호출 중에는 안전하지만
p = ctypes.cast(bytes(data), ctypes.c_char_p)   # ← 이후엔 무효 ★

# ✅ 버퍼를 변수로 유지
buf = (ctypes.c_ubyte * len(data)).from_buffer_copy(data)
lib.process(buf, len(data))         # buf 가 살아 있는 동안 유효

# ✅ 제자리 수정이 필요하면 from_buffer (복사 없음)
arr = bytearray(data)
buf = (ctypes.c_ubyte * len(arr)).from_buffer(arr)   # ★ arr 를 직접 봅니다
lib.invert(buf, len(arr))
print(arr)                          # 바뀌어 있습니다

# numpy 는 .ctypes 로 (앞의 예제)
#   단, 배열이 GC 되지 않도록 참조를 유지해야 합니다

# ★ Rust 쪽이 포인터를 보관한다면 (콜백 등록 등)
#   파이썬 쪽 객체의 수명을 명시적으로 관리해야 합니다.
#   이 경계에서 나는 크래시는 재현이 어렵습니다 — 문서에 규약을 적으세요 (f06)

문자열을 돌려주는 정석 ★

use std::ffi::{CString, CStr, c_char};

#[no_mangle]
pub extern "C" fn mylib_greet(name: *const c_char) -> *mut c_char {
    let name = unsafe {
        if name.is_null() { return std::ptr::null_mut(); }
        match CStr::from_ptr(name).to_str() {
            Ok(s) => s,
            Err(_) => return std::ptr::null_mut(),
        }
    };
    let msg = format!("안녕 {name}");
    match CString::new(msg) {                    // 내부 널이 있으면 실패
        Ok(c) => c.into_raw(),                   // ★ 소유권을 C 로 넘김
        Err(_) => std::ptr::null_mut(),
    }
}

// ★ 반드시 짝이 되는 해제 함수를 제공하세요
#[no_mangle]
pub unsafe extern "C" fn mylib_string_free(s: *mut c_char) {
    if s.is_null() { return; }
    drop(CString::from_raw(s));                  // 다시 받아 해제
}

char *msg = mylib_greet("현우");
if (msg) { printf("%s\n", msg); mylib_string_free(msg); }   /* ★ 반드시 */

규약을 이름으로 드러내기 ★

★ 네 가지 패턴과 이름 규칙

① 호출자가 버퍼를 준다 — 해제 불필요 (가장 안전) ★
   int32_t mylib_encode(const uint8_t *in, size_t in_len,
                        uint8_t *out, size_t out_cap, size_t *out_len);

② 라이브러리가 할당 — 짝이 되는 free 를 제공
   char *mylib_greet(const char *name);
   void  mylib_string_free(char *s);          ← 이름에 free 를 넣으세요

③ 정적 문자열 반환 — 해제 금지
   const char *mylib_version_string(void);    ← const 로 표시 + 문서에 명시

④ 콜백으로 흘려보냄 — 콜백 안에서만 유효
   void mylib_stream(..., void (*cb)(const uint8_t*, size_t, void*), void*);

★ 문서에 반드시 적을 것 (헤더 주석으로 · f04)
   · 반환된 포인터를 누가 해제하는가
   · 해제 함수 이름
   · NULL 반환이 가능한가
   · 인자 포인터를 라이브러리가 보관하는가 (수명!)

검사 방법 ★

# ① 반복 호출하며 메모리 관찰 (가장 실용적)
python -c "
import ctypes, os, psutil
lib = ctypes.CDLL('./libmylib.so')
p = psutil.Process()
for i in range(1_000_000):
    s = lib.mylib_greet(b'test')
    lib.mylib_string_free(s)
    if i % 100_000 == 0: print(i, p.memory_info().rss // 1024, 'KB')"
#   ★ RSS 가 계속 늘면 누수입니다

# ② valgrind (리눅스 · 느립니다)
valgrind --leak-check=full --show-leak-kinds=all ./smoke

# ③ ASan (더 빠르고 정확합니다)
RUSTFLAGS="-Zsanitizer=address" cargo +nightly build \
  --target x86_64-unknown-linux-gnu
#   이중 해제 · use-after-free 를 즉시 잡습니다 ★

# ④ Miri — unsafe 로직 검증 (FFI 경계 자체는 못 봅니다 · 🔬 d07)
cargo +nightly miri test

방어적으로 설계하기

// ① 해제 후 널로 만들게 유도 — 포인터의 포인터를 받기
#[no_mangle]
pub unsafe extern "C" fn mylib_session_free(s: *mut *mut Session) {
    if s.is_null() || (*s).is_null() { return; }
    drop(Box::from_raw(*s));
    *s = std::ptr::null_mut();          // ★ 호출자의 포인터도 널로
}
// C: mylib_session_free(&sess);   → 이중 해제가 구조적으로 막힙니다

// ② 매직 넘버로 유효성 검사 (디버그 빌드에서만)
#[repr(C)]
pub struct Session { magic: u32, /* … */ }
const MAGIC: u32 = 0x4D59_4C42;

unsafe fn as_session<'a>(p: *mut Session) -> Option<&'a mut Session> {
    let s = p.as_mut()?;
    debug_assert_eq!(s.magic, MAGIC, "무효한 핸들 (이미 해제됐거나 잘못된 포인터)");
    Some(s)
}

// ③ 해제 카운터로 테스트 (r11)
#[cfg(test)]
static ALIVE: AtomicUsize = AtomicUsize::new(0);
// new 에서 +1, Drop 에서 -1 → 테스트 끝에 0 인지 확인 ★

왜 free() 로 못 푸나

Rust 의 기본 할당자는 시스템 malloc 을 씁니다.
그래서 대부분의 플랫폼에서 free() 로도 '우연히' 동작합니다.

★ 하지만 의존하면 안 되는 이유
  · #[global_allocator] 를 바꾸면 즉시 깨집니다 (jemalloc · mimalloc)
  · 윈도우에서 MSVC CRT 가 다르면 힙이 다릅니다 ★
    (라이브러리는 /MD, 앱은 /MT 로 빌드된 경우 등)
  · Vec 은 크기·정렬 정보를 요구합니다 (dealloc(ptr, layout))
  · 미래에 Rust 가 할당 전략을 바꿀 수 있습니다

★ 결론
  반드시 짝이 되는 해제 함수를 제공하고,
  헤더 주석과 문서에 "free() 를 쓰지 마세요" 를 명시하세요.

// 할당자를 노출하는 방법도 있습니다 (C 쪽이 크기를 알 때)
#[no_mangle]
pub extern "C" fn mylib_alloc(size: usize) -> *mut u8;
#[no_mangle]
pub extern "C" fn mylib_dealloc(p: *mut u8, size: usize);

수명 규약을 문서로 고정하기

/// 입력 데이터를 처리합니다.
///
/// # 안전성
///
/// - `data` 는 `len` 바이트만큼 읽을 수 있는 유효한 포인터여야 합니다.
///   `len == 0` 이면 `data` 는 NULL 이어도 됩니다.
/// - 이 함수는 `data` 를 **보관하지 않습니다**. 반환 후 해제해도 됩니다.
/// - 반환된 포인터는 `mylib_buf_free` 로만 해제해야 합니다.
/// - NULL 이 반환되면 `mylib_last_error` 로 원인을 확인하세요.
/// - 스레드 안전: 여러 스레드에서 동시에 호출해도 됩니다.
#[no_mangle]
pub unsafe extern "C" fn mylib_process(data: *const u8, len: usize) -> Buf { }

// ★ 이 다섯 항목을 모든 함수에 적으세요
//   ① 포인터의 유효 범위
//   ② 라이브러리가 보관하는가 (수명)
//   ③ 반환값의 해제 책임
//   ④ 실패 표현
//   ⑤ 스레드 안전성
//
// cbindgen 이 이 주석을 헤더에 그대로 옮깁니다 (f04) —
// 그래서 C 사용자가 헤더만 보고도 규약을 알 수 있습니다 ★

함수 포인터 + user data ★

use std::ffi::c_void;

pub type ProgressFn = extern "C" fn(progress: f32, user: *mut c_void);

#[no_mangle]
pub unsafe extern "C" fn mylib_process(
    data: *const u8, len: usize,
    cb: Option<ProgressFn>,        // ★ Option 으로 널 가능 (f03)
    user: *mut c_void,             // 호출자의 컨텍스트를 그대로 돌려줌
) -> i32 {
    let Some(src) = to_slice(data, len) else { return -1 };

    for (i, chunk) in src.chunks(4096).enumerate() {
        process_chunk(chunk);
        if let Some(f) = cb {
            f(i as f32 / (src.len() / 4096) as f32, user);    // ★ 호출
        }
    }
    0
}

// ★ user 포인터가 왜 필요한가
//   C 함수 포인터는 상태를 담을 수 없습니다 (클로저가 아님).
//   그래서 호출자가 자기 객체 주소를 user 로 주고,
//   콜백 안에서 그것을 다시 캐스팅해 씁니다.

typedef struct { int count; FILE *log; } Ctx;

static void on_progress(float p, void *user) {
    Ctx *c = (Ctx *)user;                    /* ★ 되돌리기 */
    c->count++;
    fprintf(c->log, "%.0f%%\n", p * 100);
}

Ctx ctx = { 0, stdout };
mylib_process(data, len, on_progress, &ctx);

Rust 안에서 클로저를 넘기려면

// Rust 클로저를 C 콜백으로 변환하는 관용구 (🔐 o11)
extern "C" fn trampoline<F: FnMut(f32)>(p: f32, user: *mut c_void) {
    let f = unsafe { &mut *(user as *mut F) };    // ★ 되돌리기
    f(p);
}

pub fn process_with<F: FnMut(f32)>(data: &[u8], mut f: F) -> i32 {
    unsafe {
        mylib_process(
            data.as_ptr(), data.len(),
            Some(trampoline::<F>),
            &mut f as *mut F as *mut c_void,      // 클로저 주소를 user 로
        )
    }
}

// 쓰는 쪽 — 안전한 Rust API 가 됩니다 ★
process_with(&data, |p| println!("{:.0}%", p * 100.0));

// ❗ 주의
//   · 클로저가 콜백보다 오래 살아야 합니다 (여기선 함수 스코프 동안 유효)
//   · 콜백을 등록해 두고 나중에 부르는 방식이면
//     클로저를 Box 로 힙에 올려 소유권을 넘겨야 합니다 (아래)

폴링이 더 나은 경우가 많습니다 ★

// 콜백 대신 상태를 조회하게 하기
use std::sync::atomic::{AtomicU64, Ordering};

pub struct Job { done: AtomicU64, total: u64 }

#[no_mangle]
pub unsafe extern "C" fn mylib_job_progress(j: *const Job) -> f32 {
    let Some(j) = j.as_ref() else { return 0.0 };
    j.done.load(Ordering::Relaxed) as f32 / j.total as f32
}

// ★ 장점
//   · 콜백 수명·GC 문제가 없습니다
//   · 스레드 안전을 원자 연산 하나로 해결
//   · 호출자가 원하는 주기로 확인 (UI 프레임에 맞춰서)
//   · 모든 언어에서 바인딩이 단순합니다

// ★ 콜백이 꼭 필요한 경우
//   · 데이터를 스트리밍으로 흘려보낼 때 (전체를 메모리에 못 올림)
//   · 이벤트 발생 시점이 중요할 때
//   · 호출자가 흐름을 제어해야 할 때 (중단·필터)

콜백에서 지켜야 할 규칙

□ 콜백 안에서 패닉이 나면? (f09)
    Rust → 다른 언어 → Rust 로 되감기면 UB 입니다.
    → 콜백을 부르는 쪽(Rust)에서 catch_unwind 로 감쌀 수는 없습니다
      (콜백은 남의 코드입니다)
    → 각 언어 바인딩에서 예외를 잡아 에러 코드로 바꾸도록 문서화 ★

□ 콜백이 오래 걸리면?
    Rust 쪽 락을 잡은 채 콜백을 부르지 마세요 (데드락 · 🔐 o10)
    반드시 락을 놓고 부르세요

□ 콜백이 다시 라이브러리를 부르면? (재진입)
    허용할지 문서에 명시하세요. 대개 금지하는 편이 안전합니다.

□ 콜백이 반환값으로 중단을 표현할 수 있게
    typedef int (*ProgressFn)(float, void*);   /* 0 = 계속, 그 외 = 중단 */
    → 사용자가 취소할 수 있습니다 ★

□ 어느 스레드에서 불리는가
    메인 스레드 보장인지, 워커에서도 불리는지 명시하세요
    (UI 프레임워크는 대개 메인 스레드에서만 UI 를 만질 수 있습니다)

워커 스레드에서 콜백 부르기

// Rust 가 스레드를 만들어 콜백을 부르는 경우
#[no_mangle]
pub unsafe extern "C" fn mylib_start_async(
    cb: ProgressFn, user: *mut c_void,
) -> i32 {
    // ❗ 원시 포인터는 Send 가 아닙니다 — 래퍼가 필요합니다
    struct SendPtr(*mut c_void);
    unsafe impl Send for SendPtr {}          // ★ 안전성은 호출자와의 규약에 의존

    let u = SendPtr(user);
    std::thread::spawn(move || {
        let u = u;                            // 이동
        for i in 0..100 {
            cb(i as f32 / 100.0, u.0);        // 워커 스레드에서 호출 ★
        }
    });
    0
}

// ★ 문서에 반드시
//   "콜백은 임의의 스레드에서 호출됩니다. 스레드 안전하게 작성하세요."
//
// ★ 언어별 함정
//   파이썬: GIL 이 필요합니다 — ctypes 콜백은 자동으로 잡아 줍니다
//   C#: UI 스레드가 아니면 Invoke 가 필요합니다
//   Node: 이벤트 루프 밖이라 JS 를 직접 못 부릅니다 (tsfn 필요 · 🟨 j06)

더 안전한 대안 — 큐

// 콜백 대신 이벤트를 큐에 쌓고, 호출자가 꺼내 가게 하기
#[repr(C)]
pub struct Event { pub kind: i32, pub value: f64 }

#[no_mangle]
pub unsafe extern "C" fn mylib_poll_event(
    h: *mut Session, out: *mut Event,
) -> i32 {
    let Some(s) = h.as_mut() else { return -1 };
    match s.queue.pop() {                     // 논블로킹
        Some(ev) => { *out = ev; 1 }          // 1 = 이벤트 있음
        None => 0,                            // 0 = 없음
    }
}

// 호출자 (어느 언어든)
//   while (mylib_poll_event(h, &ev) > 0) { handle(ev); }
//
// ★ 장점
//   · 콜백 수명·GC·스레드 문제가 전부 사라집니다
//   · 호출자가 자기 이벤트 루프에 자연스럽게 통합합니다
//   · 게임 엔진·UI 프레임워크와 궁합이 좋습니다 ★
//   · 언어별 바인딩이 훨씬 단순해집니다
//
// ★ 단점
//   · 폴링 주기만큼 지연이 생깁니다
//   · 큐가 넘칠 때의 정책이 필요합니다 (드롭 · 블로킹 · 확장)

-sys 크레이트 관례 ★

Rust 생태계의 관례 — 두 층으로 나눕니다

  foo-sys      C 헤더를 그대로 옮긴 unsafe 바인딩 (bindgen 이 생성)
               · 빌드에서 라이브러리를 찾고 링크
               · 안전성 보장 없음

  foo          그 위의 안전한 래퍼 (사람이 작성) ★
               · RAII · Result · 슬라이스
               · 사용자는 unsafe 를 한 줄도 안 씁니다

예: libgit2-sys / git2 · openssl-sys / openssl · zstd-sys / zstd

★ 왜 나누나
  · -sys 는 기계적으로 생성되므로 버전 업데이트가 쉽습니다
  · 안전 래퍼는 설계가 필요하므로 사람이 관리합니다
  · 다른 사람이 자기만의 래퍼를 만들 수 있습니다

# foo-sys/Cargo.toml
[package]
name = "foo-sys"
links = "foo"              # ★ 같은 C 라이브러리를 두 번 링크하는 것을 막습니다

[build-dependencies]
bindgen = "0.70"
pkg-config = "0.3"

build.rs 로 생성

// build.rs
fn main() {
    // ① 시스템에서 라이브러리 찾기
    let lib = pkg_config::Config::new()
        .atleast_version("1.2")
        .probe("libfoo")
        .expect("libfoo 를 찾을 수 없습니다");
    // → cargo:rustc-link-lib · link-search 를 자동으로 출력합니다

    // ② 헤더에서 바인딩 생성
    let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .clang_args(lib.include_paths.iter()
            .map(|p| format!("-I{}", p.display())))
        .allowlist_function("foo_.*")          // ★ 필요한 것만
        .allowlist_type("Foo.*")
        .derive_debug(true)
        .derive_default(true)
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        .generate()
        .expect("bindgen 실패");

    let out = std::path::PathBuf::from(std::env::var("OUT_DIR").unwrap());
    bindings.write_to_file(out.join("bindings.rs")).unwrap();
}

// src/lib.rs (foo-sys)
#![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

bindgen 의 현실적 문제들 ★

① libclang 이 필요합니다
   빌드 머신마다 설치돼 있어야 합니다.
   → CI 에서 apt install libclang-dev 등
   → 또는 생성된 bindings.rs 를 커밋하고 feature 로 선택 ★

② 헤더 버전에 따라 결과가 달라집니다
   시스템 헤더가 다르면 다른 바인딩이 나옵니다.
   → vendored 소스를 쓰면 고정됩니다

③ 생성물이 큽니다 (수천 줄)
   → allowlist 로 필요한 것만 (위 예제)

④ 크로스 컴파일이 까다롭습니다 (🛠️ b07)
   타깃 헤더를 clang 에 알려 줘야 합니다
   → --sysroot · --target 인자

★ 실무 권장 구성
   [features]
   default = ["vendored"]
   vendored = []              # 소스를 함께 빌드 (재현 가능)
   system = []                # 시스템 라이브러리 사용
   bindgen = ["dep:bindgen"]  # 바인딩 재생성 (개발자용)
   → 기본은 커밋된 bindings.rs + vendored 소스 ★

파이썬·Node 로 다시 내보내기

★ 이 조합이 실제로 유용한 자리

  기존 C 라이브러리 (libfoo)
      ↓ bindgen
  foo-sys (unsafe)
      ↓ 사람이 작성
  foo (안전한 Rust API)
      ↓ PyO3 / napi-rs
  파이썬 · Node 모듈 ★

  왜 Rust 를 중간에 두나
    · C API 를 직접 파이썬에 노출하면 안전성 검증을 파이썬에서 못 합니다
    · Rust 층에서 RAII · 에러 변환 · 슬라이스 검증을 한 번만 하면
      파이썬·Node 양쪽이 그 혜택을 받습니다
    · 테스트도 Rust 쪽에서 한 번만 (r11)

  배포 주의
    · 동적 링크한 C 라이브러리가 있으면 wheel/npm 에 동봉해야 합니다
      auditwheel repair (파이썬 · 🐍 y11)
    · 정적 링크가 배포를 훨씬 단순하게 만듭니다 ★

문서를 읽고 확인할 것 ★

□ 스레드 안전한가
    · 전역 상태를 쓰는가 (errno 같은 것)
    · 초기화 함수가 한 번만 불려야 하는가 → OnceLock (r02)
    · 컨텍스트별로는 안전한가 → Send 만 붙이고 Sync 는 금지

□ 재진입 가능한가 (콜백 안에서 다시 부를 수 있나)

□ 반환된 포인터의 수명은
    · 정적인가 (해제 금지)
    · 다음 호출까지만 유효한가 ★ (strtok 같은 것)
    · 호출자가 해제하는가 → Drop 으로

□ 에러를 어떻게 알리나
    · 반환값 · errno · 별도 함수 (f09)
    · errno 는 스레드 로컬입니다 — 호출 직후에 읽어야 합니다

□ 시그널·longjmp 를 쓰는가 ★
    · setjmp/longjmp 가 Rust 스택을 건너뛰면 Drop 이 안 불립니다
    · libpng · libjpeg 이 이 방식을 씁니다 — 주의가 필요합니다

□ 할당자를 교체할 수 있나
    · 그렇다면 Rust 할당자와 맞춰 둘 수 있습니다

검증 도구

# ① 생성된 바인딩 확인
cargo expand --lib | head -100
find target -name bindings.rs -exec head -50 {} \;

# ② 타입 크기가 C 와 맞는지 (bindgen 이 테스트를 생성합니다)
cargo test --package foo-sys
#   bindgen 은 layout test 를 자동 생성합니다 ★
#   const _: () = assert!(size_of::<FooContext>() == 64);

# ③ ASan 으로 메모리 오류 (Miri 는 C 코드를 못 봅니다 · 🔬 d07)
RUSTFLAGS="-Zsanitizer=address" cargo +nightly test \
  --target x86_64-unknown-linux-gnu

# ④ valgrind
valgrind --leak-check=full ./target/debug/deps/foo_test-*

# ⑤ 실제 라이브러리 버전 확인
pkg-config --modversion libfoo
ldd target/release/libmylib.so | grep foo

# ★ C 라이브러리를 링크하는 순간
#   Rust 의 안전성 보장이 그 경계에서 끝납니다.
#   래퍼 층에 테스트를 두텁게 쓰는 것이 유일한 방어입니다 (r11)

catch_unwind 로 가두기 ★

use std::panic::{catch_unwind, AssertUnwindSafe};

#[no_mangle]
pub unsafe extern "C" fn mylib_process(data: *const u8, len: usize) -> i32 {
    let result = catch_unwind(AssertUnwindSafe(|| {
        let Some(src) = to_slice(data, len) else { return -1 };
        match core_process(src) {
            Ok(_) => 0,
            Err(e) => { set_last_error(e.to_string()); code_of(&e) }
        }
    }));

    match result {
        Ok(code) => code,
        Err(_) => {                                  // ★ 패닉을 잡았습니다
            set_last_error("내부 오류 (패닉)".into());
            -99
        }
    }
}

// 매크로로 반복을 줄이기
macro_rules! ffi_guard {
    ($body:expr) => {
        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| $body)) {
            Ok(v) => v,
            Err(_) => { set_last_error("내부 오류 (패닉)".into()); -99 }
        }
    };
}

#[no_mangle]
pub unsafe extern "C" fn mylib_encode(...) -> i32 {
    ffi_guard!({ /* 본문 */ })
}

에러 코드 설계 ★

// 안정된 숫자 — 한 번 배포하면 절대 바꾸지 마세요 ★
#[repr(i32)]
pub enum Code {
    Ok            = 0,
    InvalidArg    = -1,
    BufferTooSmall= -2,
    NotFound      = -3,
    IoError       = -4,
    Unsupported   = -5,
    // 새 실패는 새 번호를 추가 (기존 번호 재사용 금지)
    Internal      = -99,
}

// 스레드 로컬 마지막 에러 (errno 와 같은 방식)
use std::cell::RefCell;
thread_local! {
    static LAST_ERROR: RefCell<String> = RefCell::new(String::new());
}

fn set_last_error(msg: String) {
    LAST_ERROR.with(|e| *e.borrow_mut() = msg);
}

#[no_mangle]
pub unsafe extern "C" fn mylib_last_error(buf: *mut c_char, cap: usize) -> usize {
    LAST_ERROR.with(|e| {
        let s = e.borrow();
        let bytes = s.as_bytes();
        let n = bytes.len().min(cap.saturating_sub(1));
        if !buf.is_null() && cap > 0 {
            std::ptr::copy_nonoverlapping(bytes.as_ptr(), buf as *mut u8, n);
            *buf.add(n) = 0;                      // 널 종단 ★
        }
        bytes.len()                                // 전체 길이를 반환 (버퍼 크기 판단용)
    })
}

런타임 버전 확인

// 호출자가 기능 지원 여부를 물어볼 수 있게 하기
#[no_mangle]
pub extern "C" fn mylib_version() -> u32 {
    (1 << 16) | 2            // 1.2
}

#[no_mangle]
pub extern "C" fn mylib_has_feature(name: *const c_char) -> bool {
    let Some(n) = cstr_to_str(name) else { return false };
    matches!(n, "simd" | "threads" | "compression")
}

// ABI 버전을 따로 두는 것도 좋습니다
#[no_mangle]
pub extern "C" fn mylib_abi_version() -> u32 { 1 }
// → ABI 가 깨지면 이 숫자를 올리고, 호출자가 확인해 거부하게 합니다 ★

if (mylib_abi_version() != MYLIB_EXPECTED_ABI) {
    fprintf(stderr, "호환되지 않는 라이브러리 버전\n");
    return 1;
}

SONAME 과 심볼 버저닝

# 리눅스의 관례 — 파일 이름에 메이저 버전
#   libmylib.so.1.2.0      실제 파일
#   libmylib.so.1     →    심링크 (SONAME)
#   libmylib.so       →    심링크 (개발용)

# SONAME 설정 (build.rs 또는 .cargo/config.toml)
# rustflags = ["-C", "link-arg=-Wl,-soname,libmylib.so.1"]

# 확인
objdump -p libmylib.so | grep SONAME
readelf -d libmylib.so | grep SONAME

# ★ 왜 필요한가
#   ABI 를 깨는 변경을 하면 SONAME 의 숫자를 올립니다.
#   그러면 옛 버전과 새 버전이 시스템에 공존할 수 있고,
#   옛 앱은 옛 것을, 새 앱은 새 것을 로드합니다.

# 맥
#   install_name 을 씁니다 (-install_name @rpath/libmylib.1.dylib)
# 윈도우
#   파일 이름에 버전을 넣는 것이 관례 (mylib-1.dll)

# ★ 파이썬 wheel · npm 패키지로만 배포한다면
#   각 패키지가 자기 바이너리를 갖고 있으므로 SONAME 이 덜 중요합니다.
#   시스템 라이브러리로 배포할 때 필요합니다.

왜 UB 인가

Rust 패닉은 기본적으로 '스택 되감기(unwinding)' 입니다.
C++ 예외와 같은 메커니즘(DWARF/SEH)을 씁니다.

  Rust 함수 → C 함수 → Rust 콜백에서 패닉
                ↑
            여기를 되감으려면 C 프레임의 정리 정보가 필요한데,
            C 는 그런 정보를 갖고 있지 않습니다.
            → 정의되지 않은 동작 (대개 abort 또는 힙 손상) ★

★ 대응
  ① 모든 extern "C" 함수를 catch_unwind 로 감싸기 (이 섹션)
  ② panic = "abort" 프로파일 — 되감기 자체가 없어집니다
     · 바이너리가 작아지고 약간 빨라집니다 (🛠️ b10)
     · 하지만 패닉 = 프로세스 종료입니다
     · PyO3 에서는 쓰지 마세요 (예외로 못 바꿈 · 🐍 y03)
  ③ extern "C-unwind" — 되감기를 명시적으로 허용하는 ABI
     C++ 예외와 상호 운용해야 할 때만 (Rust 1.71+)

# 확인
cargo rustc --release -- --print cfg | grep panic
RUST_BACKTRACE=1 ./app

패닉을 아예 줄이기 ★

// catch_unwind 는 안전망이지, 설계가 아닙니다.
// FFI 층에서는 패닉이 날 일 자체를 없애세요.

// ❌ 패닉하는 코드
v[i]                        // 범위 초과 → panic
s.unwrap()                  // None → panic
a / b                       // b == 0 → panic (정수)
x as usize                  // 음수 → 릴리즈에선 거대한 수 (r02)

// ✅
v.get(i).ok_or(Code::InvalidArg)?
s.ok_or(Code::NotFound)?
a.checked_div(b).ok_or(Code::InvalidArg)?
usize::try_from(x).map_err(|_| Code::InvalidArg)?

// clippy 로 강제하기
//   #![deny(clippy::unwrap_used, clippy::expect_used,
//           clippy::indexing_slicing, clippy::panic)]
//   FFI 모듈에만 붙이면 실용적입니다 ★

// 할당 실패는 잡을 수 없습니다
//   Rust 는 OOM 시 abort 합니다 (catch_unwind 로 못 잡습니다)
//   큰 할당은 try_reserve 로 미리 확인하세요
let mut v = Vec::new();
v.try_reserve(n).map_err(|_| Code::Internal)?;

C# — P/Invoke

using System;
using System.Runtime.InteropServices;

internal static partial class Native
{
    private const string Lib = "mylib";      // libmylib.so / mylib.dll

    // .NET 7+ 의 소스 생성 방식 (더 빠릅니다) ★
    [LibraryImport(Lib)]
    internal static partial int mylib_add(int a, int b);

    [LibraryImport(Lib, StringMarshalling = StringMarshalling.Utf8)]
    internal static partial IntPtr mylib_greet(string name);

    [LibraryImport(Lib)]
    internal static partial void mylib_string_free(IntPtr s);

    // 예전 방식
    [DllImport(Lib, CallingConvention = CallingConvention.Cdecl)]
    internal static extern double mylib_distance(Point a, Point b);
}

[StructLayout(LayoutKind.Sequential)]        // ★ #[repr(C)] 에 대응 (f03)
internal struct Point { public double X, Y; }

// 안전한 래퍼
public static string Greet(string name)
{
    IntPtr p = Native.mylib_greet(name);
    if (p == IntPtr.Zero) throw new InvalidOperationException(LastError());
    try { return Marshal.PtrToStringUTF8(p)!; }
    finally { Native.mylib_string_free(p); }  // ★ 반드시 해제 (f06)
}

Go — cgo

package mylib

/*
#cgo LDFLAGS: -L${SRCDIR}/lib -lmylib
#cgo CFLAGS: -I${SRCDIR}/include
#include "mylib.h"
#include <stdlib.h>
*/
import "C"
import (
    "errors"
    "unsafe"
)

func Add(a, b int32) int32 {
    return int32(C.mylib_add(C.int32_t(a), C.int32_t(b)))
}

func Greet(name string) (string, error) {
    cname := C.CString(name)               // Go → C 문자열 (복사)
    defer C.free(unsafe.Pointer(cname))    // ★ C 힙이므로 free

    p := C.mylib_greet(cname)
    if p == nil { return "", errors.New(lastError()) }
    defer C.mylib_string_free(p)           // ★ 라이브러리 해제 함수 (f06)
    return C.GoString(p), nil
}

// 슬라이스 넘기기 — 복사 없음
func Checksum(data []byte) uint32 {
    if len(data) == 0 { return 0 }
    return uint32(C.mylib_checksum(
        (*C.uint8_t)(unsafe.Pointer(&data[0])), C.size_t(len(data))))
}
// ❗ Go 의 GC 가 데이터를 옮길 수 있습니다.
//    호출 중에는 안전하지만, C 쪽이 포인터를 보관하면 안 됩니다 ★

저장소 구조 ★

mylib/
├─ core/                Rust 핵심 로직 (순수 · 테스트 완비)
├─ ffi/                 C ABI 층 (얇게 · f01)
│  └─ cbindgen.toml
├─ include/mylib.h      생성된 헤더 (커밋)
├─ bindings/
│  ├─ python/           ctypes 래퍼 + setup.py
│  ├─ node/             koffi 래퍼 + package.json
│  ├─ csharp/           P/Invoke + .csproj
│  └─ go/               cgo 래퍼 + go.mod
├─ examples/            언어별 최소 예제 ★
└─ .github/workflows/
   ├─ build.yml         플랫폼별 바이너리
   └─ test-bindings.yml 각 언어에서 실제로 부르는 테스트 ★

★ 핵심: 각 언어 바인딩에 '스모크 테스트' 를 두고 CI 에서 돌리세요
  · 로드되는가
  · 함수가 불리는가
  · 값이 맞는가
  · 해제가 되는가 (반복 호출하며 메모리 관찰 · f06)

버전 동기화

★ 문제
  Rust 코어 1.2.0 을 배포했는데
  파이썬 패키지는 1.1.0, C# 은 1.0.0 인 상태가 되기 쉽습니다.

★ 대응
  ① 버전을 한 곳에서 관리 (Cargo.toml 이 원본)
     CI 에서 각 바인딩의 버전 파일을 갱신
  ② 런타임 버전 확인 (f09)
     바인딩이 로드 후 mylib_version() 을 확인해
     맞지 않으면 명확한 에러를 냅니다 ★
  ③ 태그 하나로 전부 배포
     git tag v1.2.0 → CI 가 crates.io · PyPI · npm · NuGet 에 동시 배포

★ 릴리스 체크리스트
  □ 헤더가 최신인가 (f04 의 git diff 검사)
  □ 모든 플랫폼 바이너리가 빌드됐는가
  □ 각 언어 스모크 테스트가 통과했는가
  □ ABI 를 깨는 변경이 있었는가 → 메이저 올림 + SONAME (f09)
  □ CHANGELOG 에 각 언어 사용자를 위한 마이그레이션 안내가 있는가

언어별 FFI 오버헤드

★ 직접 재 보세요 (환경마다 크게 다릅니다 · ⚡ e01)
  같은 빈 함수를 각 언어에서 호출해 비교하는 벤치마크를 만드세요.

일반적 경향 (상대적)
  C / C++            기준 (거의 0)
  Rust → Rust        기준
  Go (cgo)           비쌈 — 고루틴 스택 전환이 필요 ★
  C# (LibraryImport) 낮음
  C# (DllImport)     중간
  자바 (FFM)         낮음
  자바 (JNA)         높음
  파이썬 (ctypes)    높음 (🐍 y01)
  파이썬 (PyO3)      낮음
  Node (napi-rs)     낮음
  Node (koffi)       중간

★ 실무 의미
  · Go 는 cgo 호출이 비싸므로 배치가 특히 중요합니다
  · 파이썬·자바는 전용 바인딩(PyO3 · JNI)이 FFI 보다 빠릅니다
  · 어느 언어든 '경계를 적게 넘는' 설계가 답입니다 (f01 · 🐍 y01)

벤치마크 만들기

// 비교용 함수들을 라이브러리에 넣어 두면 편합니다
#[no_mangle] pub extern "C" fn mylib_noop() {}
#[no_mangle] pub extern "C" fn mylib_add_bench(a: i32, b: i32) -> i32 { a + b }
#[no_mangle] pub unsafe extern "C" fn mylib_sum_bench(p: *const f64, n: usize) -> f64 {
    if p.is_null() || n == 0 { return 0.0 }
    std::slice::from_raw_parts(p, n).iter().sum()
}

# 파이썬 쪽 측정
import timeit
print(timeit.timeit(lambda: lib.mylib_noop(), number=1_000_000))
# 이 값이 '호출 하나의 하한선' 입니다 ★

# 데이터 크기별로 재서 손익분기점을 찾으세요
for n in (10, 100, 1_000, 100_000):
    a = np.random.random(n)
    p = a.ctypes.data_as(ctypes.POINTER(ctypes.c_double))
    t_rust = timeit.timeit(lambda: lib.mylib_sum_bench(p, n), number=10_000)
    t_np   = timeit.timeit(lambda: a.sum(), number=10_000)
    print(n, t_rust, t_np)
# ★ 작은 n 에서는 numpy 가 이기고, 큰 n 에서 역전되는 지점이 보입니다

C++ 와 나란히 ★

# 매일 쓰는 명령
cargo new 이름 --lib     # 프로젝트 만들기
cargo check              # 타입 검사만 ★ 가장 자주 (build 보다 3~5배 빠름)
cargo build              # 디버그 빌드
cargo build --release    # 최적화 빌드 ★ 성능 측정은 반드시 이것
cargo run                # 빌드 + 실행
cargo test               # 테스트 (문서 예제까지 · r11)
cargo doc --open         # 문서 생성 + 브라우저
cargo add rand           # 의존성 추가
cargo clippy             # 린트 (b09)
cargo fmt                # 포맷 (b09)
cargo bench              # 벤치마크 (⚡ e01)

그 외 알아 두면 좋은 것

cargo tree               # 의존성 트리 ★
cargo tree -d            # 중복된 크레이트 (r09)
cargo tree -i syn        # 누가 syn 을 끌어왔나 (역추적)
cargo update             # 의존성 갱신 (b03)
cargo clean              # target/ 지우기
cargo build --timings    # 무엇이 오래 걸리나 → HTML 리포트 ★
cargo build -v           # 실제 rustc 명령 보기
cargo metadata --format-version 1 | jq   # 프로젝트 정보를 JSON 으로

# 유용한 서브커맨드 (cargo install 로 설치)
cargo install cargo-edit cargo-outdated cargo-audit cargo-deny
cargo install cargo-expand      # 매크로 확장 보기 (🔬 d09)
cargo install cargo-bloat       # 바이너리에서 뭐가 큰지 (b10)
cargo install cargo-nextest     # 더 빠른 테스트 러너 ★
cargo install cargo-watch       # 파일 변경 감시

언제 쓰나

// build.rs — 크레이트 컴파일 '전에' 실행됩니다
fn main() {
    // ① C 코드 함께 컴파일 (🔗 f08)
    cc::Build::new().file("src/fast.c").compile("fast");

    // ② 바인딩 생성 (bindgen · cbindgen · 🔗 f04·f08)
    // ③ 코드 생성 (프로토콜 정의 → Rust 소스)
    let out = std::env::var("OUT_DIR").unwrap();
    std::fs::write(format!("{out}/generated.rs"), gen_code()).unwrap();

    // ④ 빌드 시각 · git 해시를 상수로 ★
    let hash = std::process::Command::new("git")
        .args(["rev-parse", "--short", "HEAD"]).output()
        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
        .unwrap_or_default();
    println!("cargo:rustc-env=GIT_HASH={hash}");

    // ⑤ 조건부 컴파일 플래그
    if std::env::var("CARGO_CFG_TARGET_OS").unwrap() == "windows" {
        println!("cargo:rustc-cfg=feature=\"win\"");
    }

    // ★ 언제 다시 실행할지 반드시 지정하세요
    println!("cargo:rerun-if-changed=src/fast.c");
    println!("cargo:rerun-if-env-changed=MYLIB_PATH");
}

// 생성된 코드 쓰기
include!(concat!(env!("OUT_DIR"), "/generated.rs"));
const GIT_HASH: &str = env!("GIT_HASH");

build.rs 의 주의점

□ rerun-if 를 지정하지 않으면
    소스가 하나라도 바뀔 때마다 build.rs 가 다시 돕니다 ★
    → 빌드가 눈에 띄게 느려집니다

□ 빌드 머신에 도구를 요구합니다
    cc → C 컴파일러 · bindgen → libclang
    → 사용자가 sdist 로 설치할 때 실패의 원인 (🐍 y12)
    → 가능하면 생성물을 커밋하고 feature 로 선택 (🔗 f08)

□ 크로스 컴파일에서 헷갈립니다 (b07)
    build.rs 는 '호스트' 에서 컴파일·실행됩니다
    HOST vs TARGET 환경 변수를 구분하세요

□ 네트워크를 쓰지 마세요
    빌드 재현성이 깨지고, 오프라인 빌드가 불가능해집니다

□ 출력은 OUT_DIR 에만
    소스 디렉터리에 쓰면 crates.io 게시가 실패합니다

★ 대안을 먼저 검토하세요
    · 상수 → 그냥 코드에 쓰기
    · 코드 생성 → 절차 매크로 (🔬 d09)
    · 플랫폼 분기 → #[cfg(target_os = "...")]

지문(fingerprint)과 증분 빌드

cargo 는 크레이트마다 '지문' 을 계산해 저장합니다
  · 소스 파일 내용(mtime + 해시)
  · 컴파일 플래그 · feature 조합
  · 의존 크레이트의 지문
  · rustc 버전 · 타깃

하나라도 바뀌면 그 크레이트와 '그것에 의존하는 전부' 를 다시 빌드합니다.

★ 그래서 이런 일이 생깁니다
  · RUSTFLAGS 를 바꾸면 → 전체 재빌드
  · feature 를 켜고 끄면 → 그 크레이트 이하 전부
  · --release 와 debug 를 오가면 → 각각 별도 (둘 다 캐시됩니다)
  · CI 에서 캐시가 안 먹으면 → 매번 전체 빌드 (b08)

# 왜 다시 빌드하는지 보기
CARGO_LOG=cargo::core::compiler::fingerprint=info cargo build 2>&1 | head -30

# 무엇이 오래 걸리는지
cargo build --timings
#   → target/cargo-timings/cargo-timing.html ★ 병렬화 상태까지 보입니다

직접 rustc 를 부를 때

# cargo 없이 (의존성이 없다면)
rustc --edition 2021 -O src/lib.rs --crate-type cdylib

# cargo 가 넘기는 인자 보기
cargo build -v 2>&1 | grep rustc | head -3

# 특정 크레이트에만 플래그 주기
cargo rustc --release -p mycrate -- -C target-cpu=native

# 어셈블리·LLVM IR 보기 (⚡ e03 · 🔬 d10)
cargo rustc --release -- --emit asm
cargo rustc --release -- --emit llvm-ir
cargo asm --lib my_function          # cargo-show-asm (더 편합니다)

# 타입 크기 (r07 · 🔗 f03)
cargo +nightly rustc -- -Zprint-type-sizes

# 컴파일 단계별 시간 (🔬 d10)
cargo +nightly rustc -- -Ztime-passes

전체 구조

[package]
name = "mylib"                # crates.io 에서의 이름 (하이픈 허용)
version = "0.1.0"             # semver (b03)
edition = "2021"              # 언어 에디션 (r01)
rust-version = "1.75"         # 최소 컴파일러 버전 ★ 있으면 친절합니다
description = "빠른 텍스트 처리"
license = "MIT OR Apache-2.0" # Rust 생태계의 관례 ★
repository = "https://github.com/me/mylib"
keywords = ["text", "parser"] # 최대 5개
categories = ["text-processing"]
readme = "README.md"
exclude = ["tests/fixtures/*", "benches/data/*"]   # 게시에서 제외

[lib]
name = "mylib"                # 라이브러리 이름 (언더스코어)
crate-type = ["cdylib", "rlib"]   # 🔗 f02 · 🐍 y03

[[bin]]                       # 실행 파일 (여러 개 가능)
name = "mylib-cli"
path = "src/bin/cli.rs"

[dependencies]
serde = { version = "1", features = ["derive"] }
rand = "0.8"

[dev-dependencies]            # 테스트·벤치에서만 (배포물에 안 들어감) ★
criterion = "0.5"

[build-dependencies]          # build.rs 에서만 (b01)
cc = "1"

[features]                    # b04
default = ["std"]
std = []

[profile.release]             # b06
lto = true

의존성 표기 ★

[dependencies]
# 버전 (자세한 규칙은 b03)
serde = "1.0"                 # ^1.0 — 1.x 중 최신
serde = "=1.0.195"            # 정확히 이 버전
serde = { version = "1", default-features = false }   # 기본 feature 끄기 ★

# 경로 (워크스페이스 · b05)
mycore = { path = "../core" }

# git
mylib = { git = "https://github.com/me/mylib", tag = "v1.0" }
mylib = { git = "...", branch = "main" }
mylib = { git = "...", rev = "a1b2c3d" }      # ★ 재현성을 위해 rev 권장

# 선택적 (feature 로 켜기 · b04)
tokio = { version = "1", optional = true }

# 플랫폼별 ★
[target.'cfg(windows)'.dependencies]
winapi = "0.3"

[target.'cfg(unix)'.dependencies]
nix = "0.29"

[target.'cfg(target_arch = "wasm32")'.dependencies]
wasm-bindgen = "0.2"

# 이름 바꿔 쓰기 (같은 크레이트의 두 버전을 함께 쓸 때)
old-rand = { package = "rand", version = "0.7" }

semver 를 지키는 도구

# 공개 API 가 깨졌는지 자동 검사 ★
cargo install cargo-semver-checks
cargo semver-checks check-release

# 출력 예
#   --- failure enum_variant_added: pub enum variant added ---
#   Description: A publicly-visible enum has a new variant.
#   → #[non_exhaustive] 가 없으면 major 를 올려야 합니다 (r08)

# 공개 API 목록 뽑아 보기
cargo install cargo-public-api
cargo public-api
cargo public-api diff v0.1.0        # 이전 버전과 비교 ★

# CI 에 넣으면 실수로 API 를 깨는 것을 막습니다 (b08)

★ API 를 깨는 변경 (major 올림)
  · pub 함수·타입 제거·이름 변경
  · 함수 시그니처 변경
  · struct 에 pub 필드 추가 (non_exhaustive 없이)
  · enum 에 배리언트 추가 (non_exhaustive 없이)
  · trait 에 기본 구현 없는 메서드 추가 (🔐 o05)
  · 공개 타입의 트레이트 구현 제거
  · 최소 rust-version 올림 (논쟁적이지만 minor 로 보는 편)

의존성을 API 에 노출하지 않기 ★

// ❌ serde_json::Value 를 공개 API 에 두면
pub fn parse(s: &str) -> serde_json::Value;
// → serde_json 을 major 업데이트할 때 내 API 도 깨집니다
//   사용자도 같은 버전을 써야 합니다 (r09 의 중복 크레이트 문제)

// ✅ 내 타입으로 감싸기
pub struct Value(serde_json::Value);
pub fn parse(s: &str) -> Result<Value, Error>;

// ✅ 또는 재수출해서 버전을 명확히
pub use serde_json;                    // 사용자가 mylib::serde_json 으로 씁니다

// ★ 예외: 사실상 표준인 타입은 노출해도 됩니다
//   std 타입 · serde 트레이트 · http 크레이트의 타입 등
//   다만 Cargo.toml 에 버전 범위를 넉넉히 잡으세요

// 확인
cargo public-api | grep -v "^pub fn mylib"     # 남의 타입이 보이는지

빌드 대상 세부 설정

[lib]
name = "mylib"
path = "src/lib.rs"
test = true                  # cargo test 대상에 포함
doctest = true               # 문서 예제 실행 (r11)
bench = true
doc = true
proc-macro = false           # 절차 매크로 크레이트면 true (🔬 d09)
harness = true               # false 면 자체 main 을 씁니다 (criterion · ⚡ e01)
required-features = []

[[bench]]
name = "my_bench"
harness = false              # ★ criterion 을 쓸 때 필수

[[test]]
name = "integration"
path = "tests/main.rs"

[[example]]
name = "demo"
required-features = ["tokio"]    # 이 feature 가 있을 때만 빌드

# 자동 탐색 끄기 (파일이 많을 때 빌드가 빨라집니다)
[package]
autobins = false
autoexamples = false
autotests = false
autobenches = false

links 와 중복 방지

# 같은 C 라이브러리를 두 크레이트가 링크하면 심볼 충돌이 납니다
[package]
links = "foo"                # ★ cargo 가 중복을 막아 줍니다 (🔗 f08)

# build.rs 에서 다른 크레이트에 정보 전달
# println!("cargo:include=/path/to/include");
# → 의존하는 크레이트의 build.rs 에서
#   env::var("DEP_FOO_INCLUDE") 로 읽을 수 있습니다

# 패치 — 의존성을 임시로 교체 (버그 수정 대기 중일 때) ★
[patch.crates-io]
some-crate = { git = "https://github.com/me/some-crate", branch = "fix" }
some-crate = { path = "../some-crate-fork" }

# 워크스페이스 전체에 적용됩니다 (b05)
# ❗ crates.io 에 게시할 때는 patch 가 무시됩니다 —
#   게시 전에 정식 버전으로 되돌려야 합니다

버전 표기의 뜻 ★

★ 0.x 는 특별합니다
  semver 에서 0.x 는 "아직 안정되지 않음" 이라
  0.2 → 0.3 이 호환을 깰 수 있는 변경으로 취급됩니다.
  → Rust 생태계에는 0.x 크레이트가 아주 많습니다 (rand 0.8, pyo3 0.23)
  → 그래서 마이너 업데이트가 실제로 코드를 깨뜨립니다 ★

★ 실무 권장
  · 라이브러리를 만든다   → 넓게 ("1", "0.23")
  · 애플리케이션·서비스   → 넓게 쓰되 Cargo.lock 을 커밋 ★
  · "=1.2.3" 고정은 피하세요 — 보안 패치도 못 받습니다

Cargo.lock 을 커밋할까 ★

★ 공식 권장
  · 실행 파일 · 서비스 · 네이티브 모듈  →  커밋 ★
  · 라이브러리(crates.io 게시)          →  커밋해도 됩니다
      (게시할 때는 무시되고, CI 재현성에는 도움이 됩니다)

★ 커밋하면
  · 팀·CI·내 노트북이 정확히 같은 버전을 씁니다
  · "어제는 됐는데 오늘 CI 가 깨졌다" 가 사라집니다 ★
  · 의존성 업데이트가 명시적인 커밋이 됩니다 (리뷰 가능)

★ 커밋하지 않으면
  · 매번 최신 호환 버전을 씁니다
  · 새 버전의 버그를 바로 만납니다

# 갱신 명령
cargo update                    # 전부 (lock 범위 안에서)
cargo update -p serde           # 하나만
cargo update -p serde --precise 1.0.195
cargo upgrade                   # cargo-edit — Cargo.toml 의 범위 자체를 올림

# 무엇이 바뀌는지 미리 보기
cargo update --dry-run

고정해야 할 것 네 가지 ★

① 컴파일러 버전 — rust-toolchain.toml (r01)
   [toolchain]
   channel = "1.83.0"

② 의존성 버전 — Cargo.lock 커밋

③ 빌드 환경 — 컨테이너 이미지 태그를 고정
   FROM rust:1.83.0-slim   ← latest 를 쓰지 마세요 ★

④ 빌드 플래그 — .cargo/config.toml 에 명시
   RUSTFLAGS 를 CI 스크립트에 흩어 두지 마세요

★ 이 넷을 고정하면
  · "왜 CI 에서만 깨지지" 가 거의 사라집니다
  · 몇 달 뒤에도 같은 바이너리를 다시 만들 수 있습니다
  · 보안 사고 시 정확히 무엇이 들어갔는지 추적할 수 있습니다

# 오프라인 빌드 (에어갭 환경)
cargo vendor > .cargo/config.toml    # 의존성 소스를 vendor/ 에 복사
cargo build --offline

업데이트 정책

★ 권장 리듬
  · 주 1회 cargo audit 를 CI 로 (자동)
  · 월 1회 cargo update + 테스트 (사람이 리뷰)
  · 분기 1회 cargo upgrade 로 major 검토
  · 보안 권고가 나오면 즉시

★ 자동화
  · Dependabot / Renovate 가 Cargo 를 지원합니다
  · PR 로 올라오고 CI 가 검증합니다
  · minor/patch 는 자동 머지, major 는 사람이 검토 ★

★ 업데이트가 깨졌을 때
  cargo update -p 문제크레이트 --precise 이전버전   # 되돌리기
  cargo tree -i 문제크레이트                        # 누가 요구하는지

★ 의존성을 줄이는 것이 근본 해법입니다
  · 표준 라이브러리로 되는 일인가
  · 작은 코드를 직접 쓰는 게 나은가 (수십 줄이면 대개 그렇습니다)
  · feature 를 꺼서 하위 의존성을 없앨 수 있나 (b04) ★

cargo 는 어떻게 버전을 고르나

① 각 의존성의 요구 범위를 모읍니다
② 호환되는 것끼리 합칩니다
     A 가 serde "1.0", B 가 serde "1.2" 를 요구 → 1.x 최신 하나로
③ 호환되지 않으면 여러 벌을 넣습니다 ★
     A 가 rand "0.7", B 가 rand "0.8" → 둘 다 빌드에 포함
     (0.x 는 마이너가 다르면 비호환이므로)

★ 그래서 생기는 문제 (r09)
  · 타입이 달라 서로 못 주고받습니다
  · 바이너리가 커지고 빌드가 느려집니다
  · 전역 상태를 쓰는 크레이트는 두 벌이 각자 상태를 갖습니다 ★
      (log · tracing · rayon 스레드 풀 등에서 미묘한 버그)

# 확인
cargo tree -d

# 해결
#   ① 상위 라이브러리를 업데이트
#   ② cargo update -p 로 버전을 맞춤
#   ③ [patch] 로 임시 통일 (b02)

# 최소 버전으로 테스트 (라이브러리 저자용) ★
cargo +nightly build -Z minimal-versions
#   → "1.0" 이라고 적었는데 실제로는 1.5 기능을 쓰는 실수를 잡습니다

feature 통합의 함정 ★

같은 크레이트를 여러 곳이 쓰면 feature 가 '합쳐집니다'.

  내 크레이트: serde = { version = "1", default-features = false }
  의존성 X:    serde = { version = "1", features = ["std"] }
  → 결과: std 가 켜집니다 ★ 내가 끈 것이 무시된 셈

★ 이것이 no_std · WASM 빌드에서 자주 문제가 됩니다 (🟨 j09)

# 어떤 feature 가 최종적으로 켜졌는지 확인
cargo tree -f "{p} {f}"
cargo tree -e features -i serde

# resolver 2 (edition 2021 기본) 가 일부 개선했습니다
#   · build-dependencies 와 일반 의존성의 feature 를 분리
#   · 타깃별 의존성의 feature 를 분리
[workspace]
resolver = "2"

# 그래도 통합은 일어납니다 — 근본 해결은
#   ① 그 feature 를 켜는 의존성을 빼거나
#   ② 그 크레이트를 안 쓰거나
#   ③ 포크해서 feature 를 끄거나 ([patch])

정의와 사용

[features]
default = ["std", "compression"]      # 기본으로 켜지는 것 ★
std = []                              # 기능 이름만 (조건부 컴파일용)
compression = ["dep:zstd"]            # 선택적 의존성을 켬
python = ["dep:pyo3"]
node = ["dep:napi", "dep:napi-derive"]
full = ["compression", "python"]      # 여러 개를 묶기

[dependencies]
zstd = { version = "0.13", optional = true }     # ★ optional 이면 dep: 로 켬
pyo3 = { version = "0.23", optional = true }
napi = { version = "2", optional = true }

// 코드에서 분기
#[cfg(feature = "compression")]
pub fn compress(data: &[u8]) -> Vec<u8> { zstd::encode_all(data, 3).unwrap() }

#[cfg(not(feature = "compression"))]
pub fn compress(data: &[u8]) -> Vec<u8> { data.to_vec() }

#[cfg(feature = "python")]
pub mod python_bindings;              // 🐍 y02 · r09

// 조건 조합
#[cfg(all(feature = "std", not(target_arch = "wasm32")))]
#[cfg(any(feature = "a", feature = "b"))]

// 컴파일 타임 검사
#[cfg(all(feature = "python", feature = "node"))]
compile_error!("python 과 node 를 함께 켤 수 없습니다");

cargo build --features compression
cargo build --no-default-features
cargo build --no-default-features --features std
cargo build --all-features                # ★ CI 에서 전부 켜고 테스트

네이티브 모듈의 전형적 구성 ★

# 하나의 크레이트로 Rust 라이브러리 · 파이썬 모듈 · C ABI 를 전부
[features]
default = []
python = ["dep:pyo3"]                 # 🐍 PyO3 바인딩
capi = []                             # 🔗 C ABI 내보내기
extension-module = ["pyo3/extension-module"]

[lib]
crate-type = ["cdylib", "rlib"]       # rlib 도 두면 cargo test 가 됩니다

src/
├─ lib.rs          pub 로직 (feature 무관) ★
├─ core/           순수 Rust — 여기가 본체
├─ python.rs       #[cfg(feature = "python")]
└─ capi.rs         #[cfg(feature = "capi")]

빌드 방법
  cargo test                              # 순수 로직만 테스트 (빠름)
  maturin develop --features python       # 파이썬 모듈 (🐍 y03)
  cargo build --features capi --release   # C ABI (🔗 f02)

★ 이 구성의 이점
  · 핵심 로직을 한 번만 쓰고 여러 대상에 재사용
  · cargo test 가 파이썬 없이 돕니다 (🐍 y12 의 링크 에러 회피)
  · 각 바인딩은 얇은 변환 층만 담당

feature 조합이 깨지는 것을 막기 ★

# feature 가 5개면 조합이 32개입니다. 전부 빌드되나?
cargo install cargo-hack

cargo hack check --each-feature          # 각 feature 를 하나씩
cargo hack check --feature-powerset      # 모든 조합 ★ (느립니다)
cargo hack check --feature-powerset --depth 2   # 2개씩 조합까지만
cargo hack test --each-feature

# 자주 나는 실수
#   · feature A 를 끄면 컴파일이 안 되는 코드
#   · use 문이 cfg 밖에 있어 미사용 경고
#   · 테스트가 특정 feature 를 전제

# CI 에 최소한 이 세 가지는 넣으세요 (b08)
cargo check --no-default-features
cargo check --all-features
cargo test --all-features

문서에 표시하기

// docs.rs 에서 feature 배지 (b02)
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(feature = "compression")]
#[cfg_attr(docsrs, doc(cfg(feature = "compression")))]
pub fn compress(data: &[u8]) -> Vec<u8> { }

# README 에 표로 정리하세요

## Features

| feature | 기본 | 설명 |
|---|---|---|
| `std` | ✅ | 표준 라이브러리 (파일·네트워크) |
| `compression` | ✅ | zstd 압축 지원 |
| `python` | | PyO3 파이썬 바인딩 |
| `capi` | | C ABI 내보내기 |

```toml
mylib = { version = "1", default-features = false, features = ["std"] }
```

쓸 수 있는 조건들

#[cfg(target_os = "linux")]        // windows · macos · android · ios · wasi
#[cfg(target_family = "unix")]     // unix · windows · wasm
#[cfg(target_arch = "x86_64")]     // aarch64 · wasm32 · arm
#[cfg(target_pointer_width = "64")]
#[cfg(target_endian = "little")>]
#[cfg(target_env = "musl")]        // gnu · musl · msvc
#[cfg(target_vendor = "apple")]
#[cfg(target_feature = "avx2")]    // ⚡ e09
#[cfg(debug_assertions)]           // 디버그 빌드 ★
#[cfg(test)]                       // cargo test (r11)
#[cfg(doc)]                        // 문서 생성 중
#[cfg(feature = "x")]
#[cfg(unix)]                       // 축약형
#[cfg(windows)]

// 런타임 확인
if cfg!(debug_assertions) { }      // 매크로 형태 — 값으로 씁니다

// 전체 목록 보기
//   rustc --print cfg
//   rustc --print cfg --target wasm32-unknown-unknown

커스텀 cfg 와 검사

// build.rs 에서 설정 (b01)
println!("cargo:rustc-cfg=has_avx512");
println!("cargo::rustc-check-cfg=cfg(has_avx512)");   // 1.80+ ★ 오타 검출

// 코드에서
#[cfg(has_avx512)]
fn fast_path() { }

// ★ 1.80 부터 cargo 가 '알 수 없는 cfg' 를 경고합니다
//   warning: unexpected `cfg` condition name: `has_avx512`
//   → build.rs 에서 check-cfg 를 선언하거나
//     Cargo.toml 의 [lints.rust] 에 등록하세요

// Cargo.toml
// [lints.rust]
// unexpected_cfgs = { level = "warn", check-cfg = ['cfg(has_avx512)'] }

// ★ 이 경고가 유용한 이유
//   #[cfg(feature = "phyton")]  ← 오타
//   → 예전에는 조용히 코드가 사라졌습니다. 이제는 경고가 뜹니다.

구성

mylib/
├─ Cargo.toml              워크스페이스 루트
├─ Cargo.lock              ★ 하나만 (전체 공유)
├─ target/                 ★ 하나만 (캐시 공유)
├─ crates/
│  ├─ core/                순수 로직
│  │  ├─ Cargo.toml
│  │  └─ src/lib.rs
│  ├─ python/              PyO3 바인딩 (🐍 y02)
│  ├─ node/                napi-rs 바인딩 (🟨 j02)
│  ├─ capi/                C ABI (🔗 f02)
│  └─ cli/                 명령줄 도구
└─ xtask/                  빌드 자동화 스크립트 (아래)

# 루트 Cargo.toml
[workspace]
resolver = "2"                     # ★ edition 2021 이면 반드시
members = ["crates/*", "xtask"]
exclude = ["examples/standalone"]

# 공통 메타데이터 — 각 크레이트가 상속받습니다 ★
[workspace.package]
version = "0.3.0"
edition = "2021"
license = "MIT"
repository = "https://github.com/me/mylib"
rust-version = "1.75"

# 공통 의존성 버전 — 한 곳에서 관리 ★
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
thiserror = "2"
mylib-core = { path = "crates/core" }

[profile.release]                  # 워크스페이스 전체에 적용 (b06)
lto = true

멤버 크레이트

# crates/core/Cargo.toml
[package]
name = "mylib-core"
version.workspace = true           # ★ 루트에서 상속
edition.workspace = true
license.workspace = true

[dependencies]
serde.workspace = true             # ★ 버전을 여기 안 적습니다
thiserror.workspace = true

# crates/python/Cargo.toml
[package]
name = "mylib-python"
version.workspace = true

[lib]
name = "mylib"
crate-type = ["cdylib"]

[dependencies]
mylib-core.workspace = true
pyo3 = { version = "0.23", features = ["extension-module"] }

# 명령
cargo build                        # 전부
cargo build -p mylib-core          # 하나만 ★
cargo test --workspace             # 전부 테스트
cargo test -p mylib-core
cargo run -p mylib-cli
cargo clippy --workspace --all-targets

버전과 배포

★ 버전 정책 두 가지

① 통합 버전 (권장) — 전부 같은 버전
   version.workspace = true
   · 관리가 단순합니다
   · 릴리스 노트가 하나
   · 안 바뀐 크레이트도 버전이 올라갑니다 (문제 없음)

② 개별 버전 — 각자 관리
   · crates.io 게시 크레이트가 많을 때
   · cargo-release · release-plz 같은 도구가 필요합니다

# 자동화 도구
cargo install cargo-release
cargo release patch --workspace --execute
#   → 버전 올림 · CHANGELOG · 태그 · 게시를 한 번에

# release-plz — PR 기반 자동 릴리스 (GitHub Actions)
#   커밋 메시지(conventional commits)를 보고 버전을 정합니다

★ 의존 순서 주의
  core 를 먼저 게시해야 python 이 게시됩니다.
  cargo release 가 순서를 계산해 줍니다.

빌드 시간 관리

# 어느 크레이트가 오래 걸리나
cargo build --timings
#   → 워크스페이스 전체의 병렬화 상태가 한눈에 보입니다 ★

# 자주 바뀌는 것을 잎(leaf)에 두세요
#   core(안 바뀜) ← python(자주 바뀜)
#   이렇게 두면 python 만 고칠 때 core 는 재빌드되지 않습니다

# 개발 중에는 필요한 것만
cargo check -p mylib-python

# 테스트도 나눠서
cargo test -p mylib-core            # 빠른 단위 테스트
cargo test --workspace              # CI 에서 전부

# nextest 로 더 빠르게 ★
cargo install cargo-nextest
cargo nextest run --workspace       # 병렬화가 더 좋습니다

# 공통 의존성이 많으면 한 번만 빌드됩니다 (워크스페이스의 핵심 이점)
#   개별 저장소로 나누면 각자 target/ 을 가져 캐시가 안 겹칩니다 ★

알아 두면 좋은 규칙

· Cargo.lock 은 루트에 하나뿐입니다
    → 모든 멤버가 같은 의존성 버전을 씁니다 ★
    → 한 멤버가 serde 1.0.100 을 요구하면 전부 그것을 씁니다

· profile 설정은 루트에서만 유효합니다 (b06)
    멤버의 [profile] 은 무시되고 경고가 납니다

· feature 는 기본적으로 통합됩니다 (b03)
    cargo build 로 전부 빌드하면 모든 feature 가 켜진 상태로 합쳐집니다
    resolver = "2" 가 일부 개선했지만 완전하지는 않습니다
    → 개별 검증은 -p 로 따로 하세요 ★

· default-members 로 기본 빌드 대상을 줄일 수 있습니다
    [workspace]
    default-members = ["crates/core", "crates/cli"]
    → cargo build 가 python/node 를 건너뜁니다 (개발 편의)

· 워크스페이스 밖 크레이트를 path 로 참조하면
    그 크레이트는 워크스페이스에 포함되지 않습니다 (별도 target)

모노레포에서의 CI

# 바뀐 크레이트만 테스트하기 (큰 워크스페이스에서 유용)
- name: 변경 감지
  uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      core: ['crates/core/**']
      python: ['crates/python/**', 'crates/core/**']

- name: core 테스트
  if: steps.changes.outputs.core == 'true'
  run: cargo test -p mylib-core

# 또는 cargo 가 판단하게
cargo test --workspace           # 캐시가 있으면 안 바뀐 건 빨리 끝납니다

# 캐시 설정이 핵심입니다 (b08)
#   Swatinem/rust-cache@v2 가 target/ 과 ~/.cargo 를 캐시합니다
#   워크스페이스는 캐시 하나로 전부 커버됩니다 ★

# 게시 전 전체 검증
cargo publish --dry-run -p mylib-core
cargo package --workspace --no-verify    # 빠른 확인