9.2.2 C API의 핵심 구조와 메모리 관리 원칙

9.2.2 C API의 핵심 구조와 메모리 관리 원칙

고도로 추상화된 고수준 언어(Python, TypeScript 등) 환경에서 자동화된 가비지 컬렉션(Garbage Collection) 혜택을 누릴 수 있는 배경에는, 하위 호환 계층의 C++ 혹은 Rust 시스템 엔지니어들이 수행하는 명시적 메모리 할당(malloc) 및 해제(free)라는 저수준의 수동 통제 구조가 위치한다.
Zenoh 분산 아키텍처에서 메모리 자원의 할당(Allocation) 지점과 해당 자원의 소유권(Ownership) 반환 주기를 정확히 설계하지 못할 경우, 커널 수준의 치명적인 세그멘테이션 결함(Segmentation fault, Core dumped)이 발생하여 전체 자율주행 모빌리티 구동이 강제 중단되는 사태에 직면하게 된다.

이 절에서는 zenoh-c 라이브러리가 Rust 코어 엔진과 메모리 블록을 교환할 때 준수해야 하는 **‘메모리 소유권(Ownership) 계약 규격’**을 분석하고, C 언어 런타임에서 단 1바이트의 누수(Memory Leak)도 허용하지 않는 방어적 코딩 기법을 전개한다.

1. Zenoh 데이터 타입(z_owned, z_loaned) 및 구조체 매핑

Rust 언어의 런타임 안정성을 보장하는 핵심 철학인 소유권(Ownership) 및 빌림(Borrowing) 개념이 zenoh-c 인터페이스 스펙에 동일하게 이식되었다. 포인터 기반 시스템 언어인 C에는 이러한 생명 주기 제어 문법이 부재하므로, Zenoh 에서는 매핑되는 C 구조체의 접두어(Prefix) 명명 규칙을 통하여 소유권 정책을 강제한다.

1.0.1 메모리 생명 주기 분배 규칙

  1. z_owned_xxx_t (소유자 - Ownership 권한)
  • 개발자의 C 애플리케이션 영역에서 해당 객체를 반환받았다면, 그 메모리에 대한 영구적인 해제 책임(Deallocation Duty)을 지니게 됨을 의미한다.
  • 예: z_owned_session_t (논리적 연결 세션), z_owned_publisher_t (통신 발행자)
  • 설계 철칙: 생성된 객체의 스코프(Scope)가 종료되는 시점에 z_drop() 매크로나 z_close() 함수를 호출하여 자원을 명시적으로 파기하지 않으면, 즉각적인 메모리 누수가 발생한다.
  1. z_loaned_xxx_t (대여자 - Borrowing 권한)
  • Zenoh(Rust 코어 엔진) 측에서 C 코드 스택으로 메모리 주소 포인터의 ’읽기 권한(Read-Only)’만을 일시적으로 양도한 상태이다.
  • 예: 서브스크라이버 메인 콜백 함수 인자로 전달되는 z_sample_t 구조체의 내부 페이로드 버퍼 등.
  • 설계 철칙: 상속받은 주소 공간에 대하여 절대로 z_drop()이나 free() 명령을 인가해서는 안 된다. 이는 C 애플리케이션의 소유 자원이 아니며, 콜백 루틴이 리턴되는 즉시 Rust 런타임 엔진이 주도권을 회수하여 처리한다.

1.0.2 데이터 타입 매칭의 구현 명세

#include <zenoh.h>
#include <stdio.h>

void type_matching_example() {
    // 1. 소유권(Owner) 생성 단계
    // z_config_default() 함수가 힙 영역을 할당하여 C 블록에 소유권을 위임함
    z_owned_config_t config = z_config_default();
    
    // z_open() 내부에서 config 소유권이 이전(z_move)되고, session 소유권을 획득함
    z_owned_session_t session = z_open(z_move(config));

    // 2. 대여권(Loan) 활용 단계
    // z_keyexpr_new()는 본래 소유권 객체(owned)를 반환하지만,
    // z_loan() 매크로 래퍼를 통하여 그 참조 권한만을 대여(loaned)하여 전달할 수 있음.
    z_owned_keyexpr_t my_key = z_keyexpr_new("robot/status");
    z_publisher_put_options_t options = z_publisher_put_options_default();

    // 3. 네트워킹 데이터 전송 단계
    // [설계 원칙] C API 구조에서 인자를 타 함수로 편입시킬 때, 
    // z_move(my_key) 기반으로 메모리 해제 책임을 Rust 엔진에 완전 위임하는 철학이 사용됨.
    z_session_put(&session, z_loan(my_key), (const uint8_t *)"hello", 5, &options);

    // 4. 세션 소멸자 호출
    // 세션 파기 시 그 휘하의 모든 할당 리소스가 연쇄 파괴됨
    z_close(z_move(session));
}

대여 자원(Loaned Resource)과 영구 소유 자원(Owned Resource) 간의 컴파일-타임 런타임 책임을 명확히 판별하지 못할 경우, zenoh-c 모듈의 이식 코드는 이중 해제(Double Free)에 의한 Core Dump(Segfault) 늪에 빠지게 될 것이다.

2. 수동 메모리 할당 및 해제 메커니즘 설계 방식

저수준 C 로직 개발자들의 숙명인 가비지 청소 루틴이다. zenoh-c 규격은 변수 타입에 구애받지 않는 다형성 해제 래퍼인 z_drop() 매크로 체계를 제공한다.
그러나 단일 블록 내에서 예외가 성립하여 return이 강제되는 방어적 코드(Guard Clause) 플로우에서 생성되어 파생된 반쪽짜리 메모리 블록들을 어떻게 안정성 있게 환수시킬 것인지에 대한 엔지니어링 딜레마가 발생한다.

2.0.1 방어적 z_drop() 전술 체계 (GOTO Sweep 패턴)

최신 리눅스 커널(Linux Kernel) 개발 텍스트북 트리에 전방위적으로 이식되어 있는, 무결점 자원 스위핑(Sweeping) 아키텍처이다.

#include <zenoh.h>
#include <stdio.h>

int safe_publisher_task() {
    z_owned_config_t config = z_config_default();
    z_owned_session_t session;
    z_owned_publisher_t pub;
    z_owned_keyexpr_t key_expr;

    int ret_code = 0; // 플로우 성공/실패 마커

    // [1단계] 세션 인스턴스 초기화
    session = z_open(z_move(config));
    if (!z_session_check(&session)) {
        printf("세션 부팅 프로세스 실패\n");
        // 이 시점까지는 연산된 타 부가 자원이 전무하므로 조기 반환(Early Return) 수행
        return -1; 
    }

    // [2단계] 식별자 키 표현식 리소스 할당
    key_expr = z_keyexpr_new("robot/battery");
    // 예외 검증 분기: new 생성자 파이프 실패 시 무결성 검사
    if (!z_keyexpr_check(&key_expr)) {
        printf("키 생성 프로세스 메모리 누락\n");
        ret_code = -1;
        // [위험 구간] 이 시점 이후 발생한 오류에 대해서는,
        // 지금까지 적재된 이전 리소스 스택들을 일괄 파기하는 청소 레이블로 GOTO 점프해야 함
        goto cleanup_session; 
    }

    // [3단계] 퍼블리셔(송신 무기) 리소스 할당
    pub = z_declare_publisher(z_loan(session), z_loan(key_expr), NULL);
    if (!z_publisher_check(&pub)) {
        printf("퍼블리셔 생성 체인 실패\n");
        ret_code = -1;
        goto cleanup_key; 
    }

    // [4단계] 비즈니스 로직 정상 구현
    z_publisher_put(z_loan(pub), (const uint8_t*)"100", 3, NULL);
    printf("제어 텔레메트리 명령 송신 성공\n");


// === [메모리 환수 레이블 구역 (Teardown Phase)] ===
// 스택에 적재된 순서의 완전한 역순(LIFO)으로 수동 파괴 과정을 집행한다.
cleanup_pub:
    z_undeclare_publisher(z_move(pub)); // 퍼블리셔 인스턴스 소거
cleanup_key:
    z_drop(z_move(key_expr));         // 키 표현식 매크로 파괴
cleanup_session:
    z_close(z_move(session));         // 최종 연결 세션 연결 차단 처리

    return ret_code;
}

현대 C++ 표준의 핵심 철학인 RAII (Resource Acquisition Is Initialization) 스택 기반 회수 체계가 지원되지 않는 C 프로그래밍 한계 상황에 있어서, 이 GOTO 블록 방식은 초당 만 번 단위로 실행되는 핵심 백그라운드 코어 함수 루틴 내에서 메모리 누수 발생률 제로(0%)를 보장하는 최정점의 프로그래밍 모델이다.

3. 에러 처리(Error Handling) 구조 및 심화 디버깅 기법

C 런타임 환경은 라이브러리 함수가 실패했을 경우 관례상 NULL, 상수 -1 또는 0 단위의 에러 코드 배열만을 리턴한다.
그러나 분산 네트워크 시스템의 난해한 컨텍스트(예: “바인딩 포트 충돌 여부”, “하위 라우터 응답 타이밍 소실”) 정보를 C 변수 바이트 값만으로 단독 판별하는 것은 치명적인 문제 파악 지연을 야기한다.

3.0.1 체크(_check()) 매크로와 Rust 컨텍스트 로그 역추출 기법 구현

zenoh-c 에코시스템은 C 특유의 리턴 에러 코드 정수 방식 대신, 생성한 구조체의 유효성을 묻는 z_xxx_check() 함수 레이블을 프레임워크 표준으로 채택한다.

기본 검증 구문 명세

z_owned_session_t session = z_open(z_move(config));
if (!z_check(session)) {
    // 세션 개방의 실패 유무만을 1차 판독한다.
    printf("[크리티컬 에러] Zenoh 세션을 개방하지 못하였습니다.\n");
    // 실패의 세부 이유(Network Issue 등)는 이 단계의 C 코드 레벨에서 노출되지 않음
    exit(1);
}

에러 컨텍스트 텍스트 역추출 (런타임 환경 변수 강제 주입 모델)
실패의 상세 사유를 C 단에서 파라독스(Paradox) 규명하려면 애플리케이션 데몬이 기동되기 직전 쉘 프롬프트(Shell Environment) 상에 Rust 코어 엔진단의 로그 스피커(RUST_LOG 환경 변수) 속성을 강제로 트리거 가동해야만 한다.

# 리눅스 시스템 쉘의 C 프로그램을 실행하기 직전 전역 진단 환경 변수를 주입한다.
export RUST_LOG=zenoh=debug,zenoh_c=debug

# 에지 단말 노드 실행
./my_robot_node

# [실행결과 뷰] C 코드 계층에서는 절대 도출 불가한, 내부 연결 실패 원인이 stdout 파이프로 송출된다!
# [DEBUG] zenoh::net: Attempting to connect to TCP 192.168.0.5:7447 ...
# [WARN]  zenoh::net: Connection refused! (OS error 111)

콜백 지옥 스레드 상에서의 예외 누락 차단 보수
구독 수신 스레드의 Subscriber 콜백 안에서 메모리 포인터 속성을 잘못 이해하여 Segmentation fault를 유발하면, 메인 스핀 스레드를 타격하여 Zenoh 애플리케이션 통신망 전체가 파괴되는 치명상을 입게 된다.

void on_sample(const z_sample_t *sample, void *arg) {
    // [보안 주의 사항] sample->payload.start 구조는 절대 C 표준인 NULL('\0')로 종결되는 문자열(String)이 아니다.
    // 이는 길이가 가변적인 순수 바이너리 바이트(Raw Bytes) 덩어리 배열 구획을 의미한다.
    
    // [설계 오류] 메모리 오버스캐닝에 의한 코어 덤프 폭파 유발 트리거
    // printf("수신 페이로드: %s\n", sample->payload.start); 

    // [표준 안전 설계] 정확한 버퍼 길이 한도를 강제 지정 출력하는 루틴
    printf("수신 페이로드 바이트: %.*s\n", (int)sample->payload.len, sample->payload.start);
}

Zenoh C 통신 모델을 실무 코딩에 도입할 때, 고정 길이 제약이 없는 메모리 배열(Buffer Array)과 널 리미트 규격의 C 스트링(String) 포인터를 오인지 혼용할 경우, 이는 메모리 타락 버그(Memory Corruption)로 귀결되는 명백한 시한폭탄적 결함 요소에 해당한다.