Node.js 스트림 writable.writableLength 속성 완벽 가이드

Node.js에서 writable.writableLength 속성은 쓰기 대기열(queue)에 저장되어 있으며 아직 기록되지 않은 데이터의 바이트 수 또는 객체 수를 나타냅니다. 이 속성을 활용하면 highWaterMark 설정값과 현재 버퍼 상태를 비교하여 스트림의 데이터 흐름을 효과적으로 모니터링할 수 있습니다.

문법(Syntax)

writable.writableLength

예제 1

writableLength.js라는 이름의 파일을 생성하고 아래 코드를 복사해 넣습니다. 파일 생성 후 다음 명령어로 코드를 실행할 수 있습니다.

node writableLength.js

// writable.writableLength 속성 사용 예제
const stream = require('stream');

// 쓰기 가능한(writable) 데이터 스트림 생성
const writable = new stream.Writable({
    // 스트림에서 데이터를 기록하는 함수
    write: function(chunk, encoding, next) {
        // 데이터 청크를 문자열로 변환하여 출력
        console.log(chunk.toString());
        next();
    }
});

// cork() 호출 전 데이터 작성 - 버퍼 큐에 포함되지 않음
writable.write('Hi - This data will not be counted');

// cork() 함수 호출로 스트림 일시 중단
writable.cork();

// cork() 이후 데이터 작성 - 메모리에 버퍼링됨
writable.write('Welcome to TutorialsPoint !');
writable.write('SIMPLY LEARNING ');
writable.write('This data will be corked in the memory');

// 큐에 대기 중인 데이터 길이 출력
console.log(writable.writableLength);

실행 결과

C:\home\node>> node writableLength.js
Hi - This data will not be counted
81

위 결과에서 cork() 함수가 호출된 이후 작성된 데이터들은 버퍼 큐에 임시 저장됩니다. 따라서 writableLength는 해당 버퍼에 쌓인 데이터의 총 바이트 수인 81을 반환합니다. 반면 cork() 호출 전에 작성된 첫 번째 데이터는 즉시 처리되었기 때문에 길이 계산에 포함되지 않습니다.

예제 2: uncork()와 함께 사용하기

이번에는 uncork() 메서드를 추가하여 버퍼링된 데이터를 플러시(flush)한 후 writableLength 값이 어떻게 변하는지 살펴보겠습니다.

// writable.cork() 및 uncork() 메서드 사용 예제
const stream = require('stream');

// 쓰기 가능한(writable) 데이터 스트림 생성
const writable = new stream.Writable({
    // 스트림에서 데이터를 기록하는 함수
    write: function(chunk, encoding, next) {
        // 데이터 청크를 문자열로 변환하여 출력
        console.log(chunk.toString());
        next();
    }
});

// cork() 호출 전 데이터 작성 - 버퍼 큐에 포함되지 않음
writable.write('Hi - This data will not be counted');

// cork() 함수 호출로 스트림 일시 중단
writable.cork();

// cork() 이후 데이터 작성 - 메모리에 버퍼링됨
writable.write('Welcome to TutorialsPoint !');
writable.write('SIMPLY LEARNING ');
writable.write('This data will be corked in the memory');

// 큐에 대기 중인 데이터 길이 출력
console.log(writable.writableLength);

// uncork()로 버퍼링된 데이터 플러시
writable.uncork();

// 플러시 후 다시 길이 확인
console.log(writable.writableLength);

실행 결과

C:\home\node>> node writableLength.js
Hi - This data will not be counted
81
Welcome to TutorialsPoint !
SIMPLY LEARNING
This data will be corked in the memory
0

uncork()가 호출되면 버퍼에 저장되어 있던 모든 데이터가 출력 스트림으로 플러시됩니다. 그 결과 대기열이 비게 되어 마지막 writableLength 값이 0으로 반환되는 것을 확인할 수 있습니다.

정리

writable.writableLength 속성은 스트림 백프레셔(backpressure) 관리와 디버깅에 유용한 도구입니다. 특히 대용량 데이터를 처리하거나 highWaterMark 한도에 근접했는지 확인해야 할 때, 현재 버퍼링된 데이터 양을 실시간으로 파악하는 데 활용할 수 있습니다.