jetstream-api 0.7.0__tar.gz → 0.7.2__tar.gz

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.7.0
+Version: 0.7.2
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -54,6 +54,28 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.7.2 변경 - batchSize 기본값 262144 로 되돌림, 발행 경로 CPU 절감 (자바 v2.3.2 와 같음)
+
+- `batchSize` 기본값을 **262144** 로 되돌렸습니다. 0.7.1 의 16384 에서 파이썬 클라는 처리량이 24~35% 낮았습니다(GIL 이
+  천장이라 배치마다 드는 비용이 그대로 처리량에서 빠집니다). 멱등 기본 켜짐은 그대로입니다.
+- 발행 경로 CPU 를 줄였습니다(API 는 그대로입니다). 레코드 future 가 배치 결과 하나를 함께 가리키고(완결은 배치당 한 번),
+  키 -> 파티션 결과를 캐시하고, `send()` 가 설정값을 레코드마다 다시 읽지 않고, I/O 스레드를 깨우는 신호를 합치고,
+  ACK 하나의 배치 완결을 잠금 한 번에 묶습니다.
+- producer 는 만들 때 설정 객체를 **복사**합니다(자바 v2.3.2 도 같고, Kafka 와 같습니다). 만든 뒤 넘긴 객체를 바꿔도 그
+  producer 에는 반영되지 않습니다 - 설정을 바꾸려면 producer 를 새로 만드십시오.
+- 문서: 멱등이 거르는 것은 producer 안의 재전송뿐입니다 - 앱이 `send` 를 다시 부르면 새 레코드로 적재됩니다.
+
+## 0.7.1 변경 - producer 기본값: 멱등 켜짐, batchSize 16384 (자바 v2.3.1 과 같음)
+
+- `enableIdempotence` 기본값이 **켜짐**입니다. 멱등을 직접 정하지 않았으면 `acks(0)` 이나 `maxInFlight` 가 5 를 넘을 때
+  멱등이 저절로 꺼집니다. `enableIdempotence(True)` 를 명시하고 그 둘과 함께 쓰면 전처럼 생성 때 `ValueError` 입니다.
+- 멱등이면 토픽을 비우거나(FLUSH) epoch 가 바뀐 순간 걸려 있던 배치를 다시 보내지 않고 실패로 올립니다
+  (`MIMQE_TOPIC_FLUSHED` / `MIMQE_TOPIC_EPOCH_MISMATCH`). 0.7.0 기본처럼 조용히 다시 보내려면 `enableIdempotence(False)` 를
+  명시하십시오.
+- `batchSize` 기본값이 **16384** 입니다(파티션 배치 하나의 상한). 0.7.0 은 262144 였습니다 - 처리량이 모자라면
+  `batchSize(262144)` 처럼 늘리십시오.
+- producer 수 안내: 한 토픽의 producer(연결)는 1~4개면 충분합니다(엔진 7.0.1.3407 실측).
+
 ## 0.7.0 변경 - 발행 v2: producer 하나 = 토픽 하나, 파티션별 배치, 봉투 겹쳐 보내기 (엔진 v2 필요)
 
 발행 경로를 엔진의 새 발행 형식(v2)으로 바꿨습니다. **엔진도 v2 판이어야 합니다** - 옛 엔진에는 발행이 되지 않고
@@ -61,7 +83,8 @@ pip install jetstream-api
 
 - **producer 하나 = 토픽 하나 = 연결 하나.** `qmgr.create_producer("ORDER.EVENT", config)` 로 만듭니다. 생성할 때 토픽의
   파티션 수를 받아 두므로 없는 토픽이면 생성 단계에서 `MIMQE_OBJECT_NOT_FOUND` 로 실패합니다. 토픽이 여러 개면 토픽마다
-  producer 를 만들고, 연결이 더 필요하면 producer 를 더 만듭니다(예: 발행 스레드마다 하나).
+  producer 를 만듭니다. 한 토픽의 producer(연결)는 1~4개면 충분합니다 - 엔진 7.0.1.3407 실측에서 8개로 늘리면 어느 크기든
+  오히려 줄었습니다. 큰 레코드(1KB 급)는 1개로도 디스크가 먼저 한계에 닿고, 작은 레코드(100B 급)는 4개 근처가 최대입니다.
 - 레코드 토픽이 producer 토픽과 다르면 `send()` 가 `MIMQE_INVALID_ARGUMENT` 로 거부합니다.
 - 옛 `create_producer(config)` / `ILTopicProducer(host, port, name, config)` 모양으로 부르면 `TypeError` 가 납니다.
 - 배치는 **파티션마다** 모입니다. `batchSize`(기본 **262144**, 자바와 같음)는 파티션 배치 하나의 상한입니다. 보낼 때는

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/README.md

@@ -8,6 +8,28 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.7.2 변경 - batchSize 기본값 262144 로 되돌림, 발행 경로 CPU 절감 (자바 v2.3.2 와 같음)
+
+- `batchSize` 기본값을 **262144** 로 되돌렸습니다. 0.7.1 의 16384 에서 파이썬 클라는 처리량이 24~35% 낮았습니다(GIL 이
+  천장이라 배치마다 드는 비용이 그대로 처리량에서 빠집니다). 멱등 기본 켜짐은 그대로입니다.
+- 발행 경로 CPU 를 줄였습니다(API 는 그대로입니다). 레코드 future 가 배치 결과 하나를 함께 가리키고(완결은 배치당 한 번),
+  키 -> 파티션 결과를 캐시하고, `send()` 가 설정값을 레코드마다 다시 읽지 않고, I/O 스레드를 깨우는 신호를 합치고,
+  ACK 하나의 배치 완결을 잠금 한 번에 묶습니다.
+- producer 는 만들 때 설정 객체를 **복사**합니다(자바 v2.3.2 도 같고, Kafka 와 같습니다). 만든 뒤 넘긴 객체를 바꿔도 그
+  producer 에는 반영되지 않습니다 - 설정을 바꾸려면 producer 를 새로 만드십시오.
+- 문서: 멱등이 거르는 것은 producer 안의 재전송뿐입니다 - 앱이 `send` 를 다시 부르면 새 레코드로 적재됩니다.
+
+## 0.7.1 변경 - producer 기본값: 멱등 켜짐, batchSize 16384 (자바 v2.3.1 과 같음)
+
+- `enableIdempotence` 기본값이 **켜짐**입니다. 멱등을 직접 정하지 않았으면 `acks(0)` 이나 `maxInFlight` 가 5 를 넘을 때
+  멱등이 저절로 꺼집니다. `enableIdempotence(True)` 를 명시하고 그 둘과 함께 쓰면 전처럼 생성 때 `ValueError` 입니다.
+- 멱등이면 토픽을 비우거나(FLUSH) epoch 가 바뀐 순간 걸려 있던 배치를 다시 보내지 않고 실패로 올립니다
+  (`MIMQE_TOPIC_FLUSHED` / `MIMQE_TOPIC_EPOCH_MISMATCH`). 0.7.0 기본처럼 조용히 다시 보내려면 `enableIdempotence(False)` 를
+  명시하십시오.
+- `batchSize` 기본값이 **16384** 입니다(파티션 배치 하나의 상한). 0.7.0 은 262144 였습니다 - 처리량이 모자라면
+  `batchSize(262144)` 처럼 늘리십시오.
+- producer 수 안내: 한 토픽의 producer(연결)는 1~4개면 충분합니다(엔진 7.0.1.3407 실측).
+
 ## 0.7.0 변경 - 발행 v2: producer 하나 = 토픽 하나, 파티션별 배치, 봉투 겹쳐 보내기 (엔진 v2 필요)
 
 발행 경로를 엔진의 새 발행 형식(v2)으로 바꿨습니다. **엔진도 v2 판이어야 합니다** - 옛 엔진에는 발행이 되지 않고
@@ -15,7 +37,8 @@ pip install jetstream-api
 
 - **producer 하나 = 토픽 하나 = 연결 하나.** `qmgr.create_producer("ORDER.EVENT", config)` 로 만듭니다. 생성할 때 토픽의
   파티션 수를 받아 두므로 없는 토픽이면 생성 단계에서 `MIMQE_OBJECT_NOT_FOUND` 로 실패합니다. 토픽이 여러 개면 토픽마다
-  producer 를 만들고, 연결이 더 필요하면 producer 를 더 만듭니다(예: 발행 스레드마다 하나).
+  producer 를 만듭니다. 한 토픽의 producer(연결)는 1~4개면 충분합니다 - 엔진 7.0.1.3407 실측에서 8개로 늘리면 어느 크기든
+  오히려 줄었습니다. 큰 레코드(1KB 급)는 1개로도 디스크가 먼저 한계에 닿고, 작은 레코드(100B 급)는 4개 근처가 최대입니다.
 - 레코드 토픽이 producer 토픽과 다르면 `send()` 가 `MIMQE_INVALID_ARGUMENT` 로 거부합니다.
 - 옛 `create_producer(config)` / `ILTopicProducer(host, port, name, config)` 모양으로 부르면 `TypeError` 가 납니다.
 - 배치는 **파티션마다** 모입니다. `batchSize`(기본 **262144**, 자바와 같음)는 파티션 배치 하나의 상한입니다. 보낼 때는

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/ilink/producer.py

@@ -12,6 +12,7 @@ producer 하나 = 토픽 하나 = 전용 연결 하나 + I/O 스레드 하나다
 from __future__ import annotations
 
 import collections
+import copy
 import itertools
 import os
 import random
@@ -31,6 +32,10 @@ from .partitioner import partition_for_key
 
 #: retries 기본값. 사실상 무제한 재시도를 뜻한다.
 _INT_MAX = 2147483647
+#: 키 -> 파티션 캐시에 둘 키 수 상한(producer 당). 차면 비우고 다시 채운다
+_KEY_CACHE_MAX = 16384
+#: 키 -> 파티션 캐시에 담을 키 길이 상한(바이트). 긴 키는 매번 해시한다(캐시 메모리를 묶어 둔다)
+_KEY_CACHE_MAX_KEY = 256
 
 
 class ILProducerConfig:
@@ -58,7 +63,8 @@ class ILProducerConfig:
         self._acks = 1
         #: 배치를 모으는 시간(ms). 0 이면 모이는 대로 즉시 보낸다
         self._lingerMs = 0
-        #: 파티션 배치 하나의 크기 상한(바이트). 0.7.0 부터 자바와 같은 262144(사용자 결정)
+        # 0.7.2: 262144 로 되돌렸다(사용자 결정 2026-09-13). 0.7.1 의 16384 에서 24~35% 느렸다(GIL 천장)
+        #: 파티션 배치 하나의 크기 상한(바이트). 기본 262144
         self._batchSize = 262144
         #: 동시에 ACK 를 기다릴 봉투 수 상한
         self._maxInFlight = 5
@@ -78,14 +84,20 @@ class ILProducerConfig:
         self._maxRequestSize = 1048576
         #: 접속한 큐관리자가 받는 프레임 길이 상한(바이트) - 엔진 Runtime@MaxFrameLength 기본 128MiB
         self._maxFrameLength = ILC.MIMQ_DEFAULT_MAX_FRAME_LENGTH
-        #: 멱등 발행(PID 발급 + 시퀀스). 재전송 시 중복 적재를 막는다
-        self._enableIdempotence = False
+        # 0.7.1: Kafka 3.x 와 같은 기본 켜짐(사용자 결정 2026-09-13)
+        #: 멱등 발행(PID 발급 + 시퀀스). 재전송 시 중복 적재를 막는다. 기본 켜짐
+        self._enableIdempotence = True
+        #: 멱등을 사용자가 정했는지. 정하지 않았으면 acks=0 이나 maxInFlight > 5 에서 저절로 꺼진다
+        self._idempotenceSet = False
 
     def __setattr__(self, name: str, value) -> None:
         # 구버전 호환: cfg.acks = 0 / cfg.lingerMs = 5 같은 직접 대입을 내부 슬롯으로 돌린다.
         # (예전 이름 idempotent 도 함께 받아 준다)
         if name == "idempotent":
             name = "enableIdempotence"
+        if name == "enableIdempotence":
+            # 직접 대입도 사용자가 정한 것이다 - 기본 멱등의 저절로 끄기를 적용하지 않는다
+            object.__setattr__(self, "_idempotenceSet", True)
         if name in self._OPTIONS:
             name = "_" + name
         object.__setattr__(self, name, value)
@@ -104,7 +116,8 @@ class ILProducerConfig:
             ILProducerConfig: 체이닝을 위해 자기 자신.
 
         Note:
-            ``acks=0`` 은 멱등 발행과 함께 쓸 수 없다 (:meth:`validate` 가 거부).
+            멱등(기본 켜짐)을 정하지 않았으면 ``acks=0`` 은 멱등을 끈다. ``enableIdempotence(True)`` 를
+            명시하고 ``acks=0`` 이면 :meth:`validate` 가 거부한다.
         """
         self._acks = 0 if n == 0 else 1; return self
 
@@ -137,7 +150,8 @@ class ILProducerConfig:
             ILProducerConfig: 체이닝을 위해 자기 자신.
 
         Note:
-            뜻과 기본값이 Java 클라이언트와 같다(0.7.0).
+            뜻과 기본값이 Java 클라이언트와 같다(0.7.2 에서 262144 로 되돌렸다. 0.7.1 은 16384 였고 파이썬은
+            그 값에서 24~35% 느렸다).
             ``lingerMs`` 가 0 이면 자르는 크기로만 쓰이고(배치는 보낼 수 있게 되는 즉시 나간다),
             ``lingerMs`` 가 0 보다 크면 전송 조건도 된다(이만큼 차거나 lingerMs 가 지나면 보낸다).
             레코드 하나가 이 값보다 크면 그 레코드 혼자 배치 하나가 된다. 보낼 때는 준비된
@@ -156,9 +170,9 @@ class ILProducerConfig:
 
         Note:
             I/O 스레드가 봉투를 이만큼 겹쳐 보낸다(0.7.0). 엔진은 한 연결의 봉투를 겹쳐
-            처리하고 응답은 요청 순서대로 온다. **enableIdempotence 를 켜면 5 이하여야 한다** -
-            엔진이 파티션마다 최근 배치 5개로 중복을 가리기 때문이다(넘으면 :meth:`validate` 가
-            ``ValueError``).
+            처리하고 응답은 요청 순서대로 온다. **멱등(기본 켜짐)은 5 이하에서만 쓰인다** -
+            엔진이 파티션마다 최근 배치 5개로 중복을 가리기 때문이다. 멱등을 정하지 않았으면 5 를 넘길 때
+            멱등이 꺼지고, ``enableIdempotence(True)`` 를 명시했으면 :meth:`validate` 가 ``ValueError``.
         """
         self._maxInFlight = max(1, n); return self
 
@@ -186,8 +200,10 @@ class ILProducerConfig:
             보낸다(순서 유지). 재시도 총 시간은 :meth:`deliveryTimeoutMs` 로도 함께 제한된다.
 
         Warning:
-            재시도는 **중복 적재를 만들 수 있다.** ACK 를 못 받은 것과 서버가 적재를
-            못 한 것은 구분되지 않는다. 중복이 곤란하면 :meth:`enableIdempotence`.
+            비멱등(``enableIdempotence(False)``)이면 재시도는 **중복 적재를 만들 수 있다.** ACK 를
+            못 받은 것과 서버가 적재를 못 한 것은 구분되지 않는다. 멱등(기본 켜짐)이면 producer 안의
+            재시도는 엔진이 걸러 한 번만 적재된다. 앱이 ``send`` 를 다시 부르는 재발행은 새 레코드라
+            멱등이어도 걸러지지 않는다.
         """
         self._retries = max(0, n); return self
 
@@ -310,23 +326,34 @@ class ILProducerConfig:
         return self
 
     def enableIdempotence(self, b: bool) -> "ILProducerConfig":
-        """멱등 발행(중복 제거)을 켠다. (기본 False)
+        """멱등 발행(중복 제거)을 켜거나 끈다. (기본 켜짐 - 0.7.1)
 
         켜면 접속 시 서버에서 PID 를 발급받아 파티션 배치마다 (PID, baseSeq) 를 실어 보낸다.
-        재시도로 같은 배치가 두 번 도착해도 서버가 시퀀스로 걸러 **한 번만 적재한다.**
+        재시도로 같은 배치가 두 번 도착해도 서버가 시퀀스로 걸러 **한 번만 적재한다.** 걸러지는 것은
+        producer 안의 재시도뿐이다 - 앱이 ``send`` 를 다시 부르면 새 레코드로 적재된다.
         ``maxInFlight`` 는 5 이하여야 한다.
 
+        이 메서드로 정하지 않으면 ``acks=0`` 이거나 ``maxInFlight`` 가 5 를 넘을 때 멱등이 저절로 꺼진다.
+        명시적으로 켜고 그 둘과 함께 쓰면 :meth:`validate` 가 거부한다.
+
+        멱등이면 토픽 FLUSH / epoch 변경으로 거절된 배치(``MIMQE_TOPIC_FLUSHED`` /
+        ``MIMQE_TOPIC_EPOCH_MISMATCH``)를 다시 보내지 않고 실패로 올린다 - 엔진이 그 토픽의 번호 상태를
+        새로 잡으므로 다시 보낸 배치가 중복으로 가려져 사라질 수 있기 때문이다. 비멱등(False)은 메타데이터를
+        다시 받고 조용히 다시 보낸다.
+
         Args:
-            b (bool): True 면 멱등 발행.
+            b (bool): True 면 멱등 발행, False 면 비멱등.
 
         Returns:
             ILProducerConfig: 체이닝을 위해 자기 자신.
 
         Raises:
-            ValueError: (:meth:`validate` 시점) ``acks=0`` 과 함께 켰을 때.
+            ValueError: (:meth:`validate` 시점) 명시적으로 켜고 ``acks=0`` 이나 ``maxInFlight`` > 5 와 함께 썼을 때.
                 응답을 받지 않는 모드에서는 중복 제거가 성립하지 않는다.
         """
-        self._enableIdempotence = bool(b); return self
+        self._enableIdempotence = bool(b)
+        self._idempotenceSet = True
+        return self
 
     # ── 빌더 (snake 별칭) ───────────────────────────────────────────────
     #    Java 이름 빌더와 동작이 같다. 상세 설명은 각 원본 메서드를 참조.
@@ -404,18 +431,18 @@ class ILProducerConfig:
         return self._lingerMs
 
     def get_batch_size(self) -> int:
-        """한 봉투 누적 한도(바이트). 기본 16384.
+        """파티션 배치 하나의 크기 상한(바이트). 기본 262144.
 
         Returns:
-            int: 한 봉투 누적 한도(바이트). 기본 16384.
+            int: 파티션 배치 하나의 크기 상한(바이트). 기본 262144.
         """
         return self._batchSize
 
     def get_max_in_flight(self) -> int:
-        """동시 in-flight 배치 상한. 기본 5 (파이썬 구현은 실제로 항상 1).
+        """응답을 기다리는 봉투 수의 상한. 기본 5.
 
         Returns:
-            int: 동시 in-flight 배치 상한. 기본 5 (파이썬 구현은 실제로 항상 1).
+            int: 응답을 기다리는 봉투 수의 상한. 기본 5.
         """
         return self._maxInFlight
 
@@ -484,12 +511,15 @@ class ILProducerConfig:
         return self._maxFrameLength
 
     def is_idempotence_enabled(self) -> bool:
-        """멱등 발행이 켜져 있는지. 기본 False.
+        """실제로 쓰일 멱등 발행 여부. 기본 True.
 
         Returns:
-            bool: 멱등 발행이 켜져 있는지. 기본 False.
+            bool: 멱등 발행 여부. 정하지 않았으면 기본(True)이되, ``acks=0`` 이거나 ``maxInFlight`` 가
+            5 를 넘으면 False 다.
         """
-        return self._enableIdempotence
+        if self._idempotenceSet:
+            return self._enableIdempotence
+        return self._acks != 0 and self._maxInFlight <= 5
 
     getAcks = get_acks
     getLingerMs = get_linger_ms
@@ -507,12 +537,13 @@ class ILProducerConfig:
 
     def validate(self) -> None:
         """조합 검증. producer 생성 시 호출된다."""
-        if self._enableIdempotence and self._acks == 0:
+        # 0.7.1: 명시적으로 켰을 때만 막는다. 정하지 않은 기본 멱등은 is_idempotence_enabled() 에서 저절로 꺼진다
+        if self._idempotenceSet and self._enableIdempotence and self._acks == 0:
             raise ValueError(
                 "enableIdempotence requires acks=1"
             )
         # 0.7.0: 엔진은 (pid, 파티션)마다 최근 배치 5개로 중복을 가린다 - 그보다 많이 겹쳐 보내면 재전송이 중복으로 가려지지 않는다
-        if self._enableIdempotence and self._maxInFlight > 5:
+        if self._idempotenceSet and self._enableIdempotence and self._maxInFlight > 5:
             raise ValueError(
                 "enableIdempotence requires maxInFlight <= 5 (the engine remembers the last 5 batches"
                 " per partition; Kafka has the same limit)"
@@ -720,31 +751,75 @@ class ILRecordMetadata:
         return "ILRecordMetadata(%s[%d]@%d)" % (self.topic, self.partition, self.offset)
 
 
+class _BatchResult:
+    """파티션 배치 하나의 결과(0.7.2). 같은 배치의 레코드 future 들이 함께 가리킨다 - 완결은 배치당 한 번이다."""
+
+    __slots__ = ("topic", "partition", "event", "base_offset", "timestamp", "error")
+
+    def __init__(self, topic: str | None, partition: int) -> None:
+        """배치 결과를 만든다.
+
+        Args:
+            topic (str | None): 토픽 이름.
+            partition (int): 파티션 번호.
+        """
+        self.topic = topic
+        self.partition = partition
+        self.event = threading.Event()
+        self.base_offset = -1
+        self.timestamp = 0
+        self.error: Exception | None = None
+
+    def complete(self, base_offset: int, timestamp: int) -> None:
+        """성공으로 정한다.
+
+        Args:
+            base_offset (int): 배치 첫 레코드의 오프셋(-1 = 모름).
+            timestamp (int): 적재 시각.
+        """
+        self.base_offset = base_offset
+        self.timestamp = timestamp
+        self.event.set()
+
+    def fail(self, error: Exception) -> None:
+        """실패로 정한다.
+
+        Args:
+            error (Exception): 실패 원인.
+        """
+        self.error = error
+        self.event.set()
+
+
 class ILPublishFuture:
     """발행 완결을 기다리는 핸들. :meth:`get` 이 :class:`ILRecordMetadata` 를 돌려준다.
 
     **동기 발행은 ``send(rec).get()``** 으로 쓴다.
     """
 
-    def __init__(self, timeout_ms: int) -> None:
+    def __init__(self, timeout_ms: int, _result: "_BatchResult | None" = None, _index: int = 0) -> None:
         """**응용이 직접 만들지 않는다** - :meth:`ILTopicProducer.send` 가 돌려준다.
 
         Args:
             timeout_ms (int): :meth:`get` 에 인자를 주지 않았을 때 쓸 기본 대기
                 시간(밀리초). producer 의 ``deliveryTimeoutMs`` 가 들어온다.
+            _result (_BatchResult | None): 내부용 - 이 레코드가 든 파티션 배치의 결과(배치의 레코드들이 함께 가리킨다).
+            _index (int): 내부용 - 배치 안 순번. 좌표는 배치 첫 오프셋 + 순번이다.
         """
-        self._event = threading.Event()
+        # 0.7.2: 완결은 배치 결과 하나로 한다(레코드마다 Event 를 만들지 않는다). 좌표는 get() 때 만든다
+        self._result = _result if _result is not None else _BatchResult(None, -1)
+        self._index = _index
         self._meta: ILRecordMetadata | None = None
-        self._error: Exception | None = None
         self._timeout_ms = timeout_ms
 
     def _complete(self, meta: ILRecordMetadata) -> None:
+        # 배치 없이 만든 future 용(호환)
         self._meta = meta
-        self._event.set()
+        self._result.event.set()
 
     def _fail(self, error: Exception) -> None:
-        self._error = error
-        self._event.set()
+        self._result.error = error
+        self._result.event.set()
 
     def get(self, timeout_ms: int | None = None) -> ILRecordMetadata:
         """발행이 끝날 때까지 기다렸다가 좌표를 돌려준다.
@@ -766,12 +841,18 @@ class ILPublishFuture:
             완결은 producer 의 I/O 스레드가 한다(0.7.0). ``lingerMs`` 가 0 이어도 ``send()``
             가 돌아온 시점에 완결되어 있다는 보장은 없다 - 결과가 필요하면 이 메서드로 기다린다.
         """
+        r = self._result
         wait = (timeout_ms if timeout_ms is not None else self._timeout_ms) / 1000.0
-        if not self._event.wait(wait if wait > 0 else None):
+        if not r.event.wait(wait if wait > 0 else None):
             raise ILException(TimeoutError("publish timed out"))
-        if self._error is not None:
-            raise self._error
-        return self._meta
+        if r.error is not None:
+            raise r.error
+        m = self._meta
+        if m is None:
+            m = ILRecordMetadata(r.topic, r.partition, r.base_offset + self._index if r.base_offset >= 0 else -1,
+                                 r.timestamp)
+            self._meta = m
+        return m
 
     def is_done(self) -> bool:
         """완결(성공이든 실패든)되었는지.
@@ -779,7 +860,7 @@ class ILPublishFuture:
         Returns:
             bool: 결과가 정해졌으면 True. True 여도 :meth:`get` 이 예외를 올릴 수 있다.
         """
-        return self._event.is_set()
+        return self._result.event.is_set()
 
     def cancel(self, may_interrupt_if_running: bool = False) -> bool:
         """발행은 취소할 수 없다. **항상 False**.
@@ -936,18 +1017,19 @@ def _as_il(exc: BaseException) -> Exception:
 class _Batch:
     """파티션 배치 1개 = 와이어의 PartitionBatch 1개. ``buf`` 의 앞 52바이트가 배치 헤더다."""
 
-    __slots__ = ("partition", "created", "batch_no", "buf", "count", "futures", "callbacks",
+    __slots__ = ("partition", "created", "batch_no", "buf", "count", "result", "callbacks",
                  "closed", "done", "base_seq", "header_done", "header_pid", "retry_count",
                  "retry_at", "unknown", "size_drops", "solo")
 
-    def __init__(self, partition: int, created: float, batch_no: int) -> None:
+    def __init__(self, partition: int, created: float, batch_no: int, topic: str = "") -> None:
         self.partition = partition
         self.created = created
         #: 만든 순서. 파티션 안에서 보내야 하는 순서 = 이 순서
         self.batch_no = batch_no
         self.buf = bytearray(_BATCH_HEADER)
         self.count = 0
-        self.futures: list = []
+        #: 이 배치 레코드들의 결과(0.7.2, 배치당 하나). 레코드 future 는 이것과 배치 안 순번만 든다
+        self.result = _BatchResult(topic, partition)
         self.callbacks: list | None = None
         #: 더 붙이지 않는다(batchSize 에 닿음, drain 이 가져감, 되돌림)
         self.closed = False
@@ -1001,16 +1083,18 @@ class ILTopicProducer:
     """토픽 하나에 묶인 발행자. ``ILQmgr.create_producer(topic, config)`` 로 얻는다. (0.7.0 발행 v2)
 
     producer 하나 = 토픽 하나 = 전용 연결 하나(clientName + ``"-PRD"``) + I/O 스레드 하나다. 생성할 때
-    연결을 열고 토픽의 파티션 수·epoch·세그먼트 크기를 받아 둔다. 연결이 여러 개 필요하면 producer 를
-    여러 개 만든다(예: 발행 스레드마다 하나).
+    연결을 열고 토픽의 파티션 수·epoch·세그먼트 크기를 받아 둔다. 한 토픽의 producer(연결)는 1~4개면
+    충분하다 - 엔진 7.0.1.3407 실측에서 8개로 늘리면 어느 크기든 오히려 줄었다. 큰 레코드(1KB 급)는 1개로도
+    디스크가 먼저 한계에 닿고, 작은 레코드(100B 급)는 4개 근처가 최대다.
 
     보장:
 
     - **순서**: 한 파티션 안에서는 ``send`` 순서대로 적재된다. 파티션 사이의 순서는 보장하지 않는다.
       비멱등에서 FLUSH TOPIC 과 겹친 배치를 다시 보낼 때는 이미 나가 있던 같은 파티션의 뒤 배치가
       먼저 적재될 수 있다.
-    - **전달**: ``acks=1`` + 재시도 = at-least-once. ``enableIdempotence(True)`` 면 재전송이 엔진에서 중복
-      제거되어 유실/중복이 없다. ``acks=0`` = at-most-once.
+    - **전달**: ``acks=1`` + 재시도 = at-least-once. 멱등(기본 켜짐)이면 producer 안의 재전송이 엔진에서
+      중복 제거되어 중복 적재가 없다(적재하지 못한 배치는 future 가 실패로 알린다). 앱이 ``send`` 를 다시
+      부르면 새 레코드라 멱등이어도 걸러지지 않는다. ``acks=0`` = at-most-once.
     - **재시도**: 연결 단절, 비멱등의 FLUSHED / epoch 불일치(적재되지 않은 것이 확정된 거절), 멱등의
       순서 오류다. 그 밖의 거절(토픽 없음, 너무 큼 등)은 재시도 없이 그 배치의 future 가 실패한다.
       PID 가 무효가 되면 PID 를 다시 받고 seq 를 0 부터 다시 매긴다.
@@ -1036,13 +1120,14 @@ class ILTopicProducer:
             port (int | None): 포트. ``host`` 에 ``:포트`` 가 붙어 있으면 생략한다.
             client_name (str): 큐 관리자에 등록될 클라이언트 이름. 기본 ``"PRODUCER"``.
             topic (str): 발행할 토픽 이름. **필수.** 이 producer 는 이 토픽에만 발행한다.
-            config (ILProducerConfig | None): 발행 설정. 기본 None 이면 전 항목 기본값.
+            config (ILProducerConfig | None): 발행 설정. 기본 None 이면 전 항목 기본값. 생성 때 복사한다 -
+                이후 넘긴 객체를 바꿔도 이 producer 에는 반영되지 않는다.
 
         Raises:
             TypeError: ``topic`` 이 토픽 이름(str)이 아닐 때 - 0.6.x 의
                 ``ILTopicProducer(host, port, name, config)`` 모양으로 부르면 여기서 멈춘다.
-            ValueError: ``topic`` 이 비었거나 ``config`` 조합이 잘못됐을 때(멱등 + ``acks=0``,
-                멱등 + ``maxInFlight`` > 5).
+            ValueError: ``topic`` 이 비었거나 ``config`` 조합이 잘못됐을 때(명시적으로 켠 멱등 + ``acks=0``,
+                명시적으로 켠 멱등 + ``maxInFlight`` > 5).
             ILOperationException: 주소 목록이 비었거나, 접속·토픽 조회를 거절당했을 때
                 (없는 토픽이면 ``MIMQE_OBJECT_NOT_FOUND``).
             ILException: 후보 주소 어디에도 접속하지 못했을 때.
@@ -1058,7 +1143,8 @@ class ILTopicProducer:
                 " (got %s) - since 0.7.0 a producer publishes to one topic" % type(topic).__name__)
         if not topic:
             raise ValueError("topic must not be empty - a producer publishes to one topic")
-        self.config = config or ILProducerConfig()
+        # 0.7.2: 설정을 생성 때 복사한다(Kafka·자바와 같다) - 넘긴 객체를 나중에 바꿔도 이 producer 에는 반영되지 않는다
+        self.config = copy.copy(config) if config is not None else ILProducerConfig()
         self.config.validate()
         cfg = self.config
         self.topic = topic
@@ -1075,6 +1161,13 @@ class ILTopicProducer:
         self._backoff = cfg.get_retry_backoff_ms() / 1000.0
         self._request_timeout = cfg.get_request_timeout_ms() / 1000.0
         self._delivery_timeout = cfg.get_delivery_timeout_ms() / 1000.0
+        # 0.7.2: send() 가 레코드마다 부르던 설정 게터를 생성 때 한 번 읽는다
+        self._delivery_timeout_ms = cfg.get_delivery_timeout_ms()
+        self._max_request_size = cfg.get_max_request_size()
+        self._max_frame_length = cfg.get_max_frame_length()
+        self._buffer_memory = cfg.get_buffer_memory()
+        self._max_block = cfg.get_max_block_ms() / 1000.0
+        self._batch_size = cfg.get_batch_size()
         #: 봉투 본문(IL 헤더 뒤) 상한 = min(maxRequestSize, maxFrameLength - 25)
         self._max_env_content = min(cfg.get_max_request_size(),
                                     cfg.get_max_frame_length() - ILC.SZ_IL_HEADER)
@@ -1111,6 +1204,10 @@ class ILTopicProducer:
         self._used = 0
         self._sticky = -1
         self._sticky_bytes = 0
+        #: 키 -> 파티션 캐시(0.7.2). 파티션 수가 바뀌면 비운다
+        self._key_parts: dict = {}
+        #: 깨울 신호를 이미 보냈고 I/O 스레드가 아직 비우지 않았다(0.7.2 - 신호를 합친다)
+        self._wake_pending = False
         self._pid = -1
         #: drain 이 큐에서 꺼낸 배치를 아직 in-flight 에 올리지(acks=0 이면 완결하지) 않은 동안 1 - flush 가 먼저 돌아가지 않게
         self._draining = 0
@@ -1265,6 +1362,8 @@ class ILTopicProducer:
                 self._parts = parts
                 if self._sticky >= n:
                     self._sticky = -1
+            if n != self._partition_count:
+                self._key_parts.clear()
             self._partition_count = n
             self._cv.notify_all()
         if len(self._next_seq) != n:
@@ -1355,22 +1454,21 @@ class ILTopicProducer:
         rec_size = _RECORD_OVERHEAD + kl + pl + len(value)
         # 이 레코드 혼자 실린 봉투의 본문 크기
         alone = _ENVELOPE_FIXED + len(self._topic_bytes) + _BATCH_HEADER + rec_size
-        if alone > cfg.get_max_request_size():
+        if alone > self._max_request_size:
             raise ILOperationException("MIMQE_MSG_SIZE_OVER (record too large: %d > maxRequestSize %d - envelope carrying"
-                                       " this record alone)" % (alone, cfg.get_max_request_size()))
+                                       " this record alone)" % (alone, self._max_request_size))
         # 엔진은 Runtime@MaxFrameLength(기본 128MiB) 를 넘는 프레임을 사유 없이 끊는다 - 보내기 전에 막는다
-        if alone + ILC.SZ_IL_HEADER > cfg.get_max_frame_length():
+        if alone + ILC.SZ_IL_HEADER > self._max_frame_length:
             raise ILOperationException(
                 "MIMQE_MSG_SIZE_OVER (record too large: frame %d > maxFrameLength %d - the engine drops the connection"
                 " over its Runtime@MaxFrameLength; raise both if the server allows more)"
-                % (alone + ILC.SZ_IL_HEADER, cfg.get_max_frame_length()))
+                % (alone + ILC.SZ_IL_HEADER, self._max_frame_length))
         rec = b"".join((_I32.pack(kl if key else -1), key or b"",
                         _I32.pack(pl if props else -1), props or b"",
                         _I32.pack(len(value)), value))
-        future = ILPublishFuture(cfg.get_delivery_timeout_ms())
         with self._cv:
-            # maxBlockMs 는 버퍼 대기의 상한이다(Kafka max.block.ms)
-            deadline = time.monotonic() + cfg.get_max_block_ms() / 1000.0
+            # maxBlockMs 는 버퍼 대기의 상한이다(Kafka max.block.ms). 기한은 기다려야 할 때만 잡는다
+            deadline = None
             partition = self._choose_partition(record.partition, key)
             while True:
                 if self._fatal is not None:
@@ -1392,16 +1490,18 @@ class ILTopicProducer:
                 fresh = (b is None or b.closed or len(b.buf) + rec_size > self._batch_limit
                          or (seg > 0 and len(b.buf) + rec_size + (b.count + 1) * self._v3_per_record > seg))
                 need = rec_size + (_BATCH_HEADER if fresh else 0)
-                if need > cfg.get_buffer_memory():
+                if need > self._buffer_memory:
                     raise ILOperationException("MIMQE_MSG_SIZE_OVER (record too large: needs %d bytes of buffer"
-                                               " > bufferMemory %d)" % (need, cfg.get_buffer_memory()))
-                if self._used + need > cfg.get_buffer_memory():
+                                               " > bufferMemory %d)" % (need, self._buffer_memory))
+                if self._used + need > self._buffer_memory:
                     # 버퍼 확보(가득이면 maxBlockMs 대기). 기다리는 사이 배치가 나가거나 파티션 수가 바뀔 수 있어 처음부터 다시 본다
+                    if deadline is None:
+                        deadline = time.monotonic() + self._max_block
                     remain = deadline - time.monotonic()
                     if remain <= 0:
                         # 부하 문제다(Kafka BufferExhaustedException) - 큐 가득과 같은 분류(재시도 가능)로 올린다
                         raise ILOperationException("MIMQE_QUEUE_FULL (buffer memory full %d/%d - blocked over maxBlockMs)"
-                                                   % (self._used, cfg.get_buffer_memory()))
+                                                   % (self._used, self._buffer_memory))
                     self._cv.wait(remain)
                     continue
                 wake = False
@@ -1409,14 +1509,14 @@ class ILTopicProducer:
                     if b is not None:
                         b.closed = True
                     self._batch_counter += 1
-                    b = _Batch(partition, time.monotonic(), self._batch_counter)
+                    b = _Batch(partition, time.monotonic(), self._batch_counter, self.topic)
                     q.append(b)
                     self._queued += 1
                     self._used += _BATCH_HEADER
                     wake = True
                 b.buf += rec
                 self._used += rec_size
-                b.futures.append(future)
+                future = ILPublishFuture(self._delivery_timeout_ms, b.result, b.count)
                 if callback is not None:
                     if b.callbacks is None:
                         b.callbacks = [None] * b.count
@@ -1445,7 +1545,15 @@ class ILTopicProducer:
                                            % (explicit, n - 1))
             return explicit
         if key:
-            return partition_for_key(key, n)
+            # 0.7.2: 같은 키는 같은 파티션이다 - 파티션 수가 그대로인 동안 결과를 캐시한다(순수 파이썬 murmur2 가 레코드당 수 us)
+            p = self._key_parts.get(key)
+            if p is None:
+                p = partition_for_key(key, n)
+                if len(key) <= _KEY_CACHE_MAX_KEY:
+                    if len(self._key_parts) >= _KEY_CACHE_MAX:
+                        self._key_parts.clear()
+                    self._key_parts[key] = p
+            return p
         if self._sticky < 0 or self._sticky >= n:
             self._sticky = random.randrange(n)
             self._sticky_bytes = 0
@@ -1454,7 +1562,7 @@ class ILTopicProducer:
     def _sticky_advance(self, nbytes: int) -> None:
         """키 없는 레코드를 붙인 만큼 센다. ``batchSize`` 를 채우면 다음 파티션으로 넘긴다(Kafka 3.3+ 균일 스티키)."""
         self._sticky_bytes += nbytes
-        if self._sticky_bytes >= self.config.get_batch_size():
+        if self._sticky_bytes >= self._batch_size:
             self._sticky = (self._sticky + 1) % self._partition_count
             self._sticky_bytes = 0
 
@@ -1573,10 +1681,15 @@ class ILTopicProducer:
 
     # ── I/O 스레드 ───────────────────────────────────────────────────────
     def _wakeup(self) -> None:
+        # 0.7.2: 깨울 신호가 이미 가 있으면(I/O 스레드가 아직 비우지 않았으면) 다시 쓰지 않는다 - 배치를 열고 닫을 때마다 쓰던
+        #   시스템 호출을 합친다. I/O 스레드는 신호를 비운 뒤에 이 표시를 내리고, 그다음에 큐를 본다
+        if self._wake_pending:
+            return
+        self._wake_pending = True
         try:
             self._wake_w.send(b"\x00")
         except OSError:
-            pass
+            self._wake_pending = False
 
     def _drain_wake(self) -> None:
         try:
@@ -1584,6 +1697,8 @@ class ILTopicProducer:
                 pass
         except OSError:
             pass
+        # 비운 뒤에 내린다. 먼저 내리면 비우는 사이 온 신호를 먹고도 표시가 올라간 채 남아 다음 깨우기가 막힐 수 있다
+        self._wake_pending = False
 
     def _wake_waiters(self) -> None:
         with self._cv:
@@ -1942,45 +2057,56 @@ class ILTopicProducer:
             raise ConnectionError(results[0][4] or "MIMQE_INVALID_PID")
         now = time.monotonic()
         again = []
-        for b, (code, off, ts, exp, reason) in zip(env.batches, results):
-            # seq 틈: 이 배치의 어느 시도도 적재됐을 수 없는데(결과를 모른 적이 없다) 엔진이 중복이라 한다 = 같은 파티션의 뒤
-            #   배치가 먼저 기준선으로 적재돼(두 봉투 사이 리더 교체 등) 이 번호가 틈으로 남았다. 성공으로 올리면 조용한 유실이다.
-            if code == ILC.MIMQ_TOPIC_PUBLISH_DUPLICATE and self._idem and b.base_seq >= 0 and not b.unknown:
-                self._complete_batch(b, -1, 0, ILOperationException(
-                    "MIMQE_OUT_OF_ORDER_SEQUENCE (sequence gap: partition %d seq %d..%d was never stored but the engine"
-                    " answered duplicate - a later batch of this partition was stored first)"
-                    % (b.partition, b.base_seq, b.base_seq + b.count - 1)))
-                continue
-            if code == ILC.MIMQ_SUCCESSFUL_TOPIC_PUBLISH or code == ILC.MIMQ_TOPIC_PUBLISH_DUPLICATE:
-                # 중복 응답은 원 좌표로 성공한다. 엔진 링 밖이면 baseOffset 이 -1 이다.
-                self._pid_resets = 0
-                if self._idem and b.base_seq >= 0 and b.partition < len(self._acked_seq):
-                    last = b.base_seq + b.count - 1
-                    if last > self._acked_seq[b.partition]:
-                        self._acked_seq[b.partition] = last
-                self._complete_batch(b, off, ts, None)
-                continue
-            # epoch 가 바뀌었거나(FLUSH / 재생성), 토픽이 비워지는 중이거나, 세그먼트가 줄었다 - 메타데이터를 다시 받는다
-            if code in (ILC.MIMQ_TOPIC_PUBLISH_EPOCH_MISMATCH, ILC.MIMQ_TOPIC_PUBLISH_FLUSHED,
-                        ILC.MIMQ_TOPIC_PUBLISH_TOO_LARGE):
-                self._meta_stale = True
-            expected = exp if code == ILC.MIMQ_OUT_OF_ORDER_SEQUENCE else -1
-            if self._idem and b.base_seq >= 0:
-                # 배치별 거절 = 이번 시도는 적재되지 않았다(엔진 계약). 번호를 돌려받고 재번호를 건다.
-                #   단 앞선 시도가 답 없이 끝난 배치(unknown)는 그때 적재됐을 수 있다 - 순서 오류가 아니면 번호를
-                #   돌려받지 않는다. 돌려받아 다음 새 배치에 주면 그 배치가 엔진에서 중복 응답으로 사라진다(유실).
-                if expected >= 0 or not b.unknown:
-                    self._note_rejected(b.partition, b.base_seq, expected)
-                b.base_seq = -1
-                b.header_done = False
-            if self._can_retry(b, code, expected >= 0, now):
-                b.retry_count += 1
-                b.retry_at = now + self._backoff
-                again.append(b)
-            else:
-                self._complete_batch(b, -1, 0, _batch_error(code, reason))
+        # 0.7.2: 이 ACK 에서 완결한 배치들의 버퍼는 아래 잠금 한 번에 반납한다(배치마다 잠금을 잡지 않는다)
+        freed = 0
+        try:
+            for b, (code, off, ts, exp, reason) in zip(env.batches, results):
+                # seq 틈: 이 배치의 어느 시도도 적재됐을 수 없는데(결과를 모른 적이 없다) 엔진이 중복이라 한다 = 같은 파티션의
+                #   뒤 배치가 먼저 기준선으로 적재돼(두 봉투 사이 리더 교체 등) 이 번호가 틈으로 남았다. 성공으로 올리면 조용한 유실이다.
+                if code == ILC.MIMQ_TOPIC_PUBLISH_DUPLICATE and self._idem and b.base_seq >= 0 and not b.unknown:
+                    freed += self._complete_batch(b, -1, 0, ILOperationException(
+                        "MIMQE_OUT_OF_ORDER_SEQUENCE (sequence gap: partition %d seq %d..%d was never stored but the engine"
+                        " answered duplicate - a later batch of this partition was stored first)"
+                        % (b.partition, b.base_seq, b.base_seq + b.count - 1)), release=False)
+                    continue
+                if code == ILC.MIMQ_SUCCESSFUL_TOPIC_PUBLISH or code == ILC.MIMQ_TOPIC_PUBLISH_DUPLICATE:
+                    # 중복 응답은 원 좌표로 성공한다. 엔진 링 밖이면 baseOffset 이 -1 이다.
+                    self._pid_resets = 0
+                    if self._idem and b.base_seq >= 0 and b.partition < len(self._acked_seq):
+                        last = b.base_seq + b.count - 1
+                        if last > self._acked_seq[b.partition]:
+                            self._acked_seq[b.partition] = last
+                    freed += self._complete_batch(b, off, ts, None, release=False)
+                    continue
+                # epoch 가 바뀌었거나(FLUSH / 재생성), 토픽이 비워지는 중이거나, 세그먼트가 줄었다 - 메타데이터를 다시 받는다
+                if code in (ILC.MIMQ_TOPIC_PUBLISH_EPOCH_MISMATCH, ILC.MIMQ_TOPIC_PUBLISH_FLUSHED,
+                            ILC.MIMQ_TOPIC_PUBLISH_TOO_LARGE):
+                    self._meta_stale = True
+                expected = exp if code == ILC.MIMQ_OUT_OF_ORDER_SEQUENCE else -1
+                if self._idem and b.base_seq >= 0:
+                    # 배치별 거절 = 이번 시도는 적재되지 않았다(엔진 계약). 번호를 돌려받고 재번호를 건다.
+                    #   단 앞선 시도가 답 없이 끝난 배치(unknown)는 그때 적재됐을 수 있다 - 순서 오류가 아니면 번호를
+                    #   돌려받지 않는다. 돌려받아 다음 새 배치에 주면 그 배치가 엔진에서 중복 응답으로 사라진다(유실).
+                    if expected >= 0 or not b.unknown:
+                        self._note_rejected(b.partition, b.base_seq, expected)
+                    b.base_seq = -1
+                    b.header_done = False
+                if self._can_retry(b, code, expected >= 0, now):
+                    b.retry_count += 1
+                    b.retry_at = now + self._backoff
+                    again.append(b)
+                else:
+                    freed += self._complete_batch(b, -1, 0, _batch_error(code, reason), release=False)
+        except BaseException:
+            # 도중에 끊겨도 이미 완결한 배치의 버퍼는 돌려준다
+            if freed:
+                with self._cv:
+                    self._used -= freed
+                    self._cv.notify_all()
+            raise
         gone: list = []
         with self._cv:
+            self._used -= freed
             # 배치는 되돌린 것을 큐에 넣은 **뒤에** in-flight 에서 뺀다. 먼저 빼면 그 사이 flush() 가 비었다고 보고 돌아간다.
             if again:
                 gone = self._requeue_batches(again)
@@ -2059,30 +2185,40 @@ class ILTopicProducer:
             self._queued += 1
         return gone
 
-    def _complete_batch(self, b: _Batch, base_offset: int, timestamp: int, err: Exception | None) -> None:
+    def _complete_batch(self, b: _Batch, base_offset: int, timestamp: int, err: Exception | None,
+                        release: bool = True) -> int:
+        """배치 하나를 완결한다. 레코드 future 들은 배치 결과 하나를 함께 가리키므로 결과를 한 번 정하면 모두 풀린다(0.7.2).
+
+        ``release`` 가 False 면 버퍼 반납(``self._used``)과 대기자 깨우기를 부른 쪽이 한꺼번에 한다 -
+        ACK 하나에 든 배치들을 잠금 한 번에 반납하려는 것이다. 반납할 바이트 수를 돌려준다.
+        """
         if b.done:
-            return
+            return 0
         b.done = True
-        with self._cv:
-            self._used -= len(b.buf)
-            self._cv.notify_all()
-        futures, callbacks = b.futures, b.callbacks
-        b.futures = []
+        freed = len(b.buf)
+        if release:
+            with self._cv:
+                self._used -= freed
+                self._cv.notify_all()
+        r = b.result
+        if err is None:
+            r.complete(base_offset, timestamp)
+        else:
+            r.fail(err)
+        callbacks = b.callbacks
         b.callbacks = None
-        topic = self.topic
-        for i, fut in enumerate(futures):
-            meta = None
-            if err is None:
-                meta = ILRecordMetadata(topic, b.partition, base_offset + i if base_offset >= 0 else -1, timestamp)
-                fut._complete(meta)
-            else:
-                fut._fail(err)
-            cb = callbacks[i] if callbacks is not None else None
-            if cb is not None:
+        if callbacks:
+            topic = self.topic
+            for i, cb in enumerate(callbacks):
+                if cb is None:
+                    continue
+                meta = (ILRecordMetadata(topic, b.partition, base_offset + i if base_offset >= 0 else -1, timestamp)
+                        if err is None else None)
                 try:
                     cb(meta, err)
                 except Exception:               # noqa: BLE001 - 콜백 예외는 무시한다(계약)
                     pass
+        return freed
 
     def _fail_batches(self, batches, err: Exception | None) -> None:
         """파티션이 없어진 배치 등을 실패시킨다(self._cv 밖에서 부른다)."""

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/ilink/qmgr.py

@@ -1139,7 +1139,7 @@ class ILQmgr:
         Args:
             topic (str): 발행할 토픽 이름. 이 producer 는 이 토픽에만 발행한다.
             config (ILProducerConfig | None): 발행 설정. 기본 None 이면 전 항목
-                기본값(acks=1 / linger 0 / batch 256KB / maxInFlight 5 / 멱등 꺼짐).
+                기본값(acks=1 / linger 0 / batch 256KB / maxInFlight 5 / 멱등 켜짐).
 
         Returns:
             ILTopicProducer: 발행자. 다 쓰면 ``close()`` 로 닫는다.
@@ -1149,13 +1149,16 @@ class ILQmgr:
                 부르면 여기서 멈춘다.
             ILOperationException: 아직 :meth:`connect` 하지 않았을 때, 없는 토픽일 때
                 (``MIMQE_OBJECT_NOT_FOUND``).
-            ValueError: ``config`` 조합이 잘못됐을 때(멱등 + ``acks=0``, 멱등 + ``maxInFlight`` > 5).
+            ValueError: ``config`` 조합이 잘못됐을 때(명시적으로 켠 멱등 + ``acks=0``, 명시적으로 켠 멱등 +
+                ``maxInFlight`` > 5).
             ILException: 발행 전용 연결을 맺지 못했을 때.
 
         Note:
             발행자는 **전용 연결**을 하나 연다(클라이언트 이름 뒤에 ``"-PRD"`` 가 붙는다). 생성할 때 토픽의
             파티션 수를 받아 두고, I/O 스레드가 봉투를 겹쳐 보낸다. 토픽이 여러 개면 토픽마다 producer 를
-            만들고, 연결이 더 필요하면 producer 를 더 만든다(예: 발행 스레드마다 하나).
+            만든다. 한 토픽의 producer 는 1~4개면 충분하다 - 엔진 7.0.1.3407 실측에서 8개로 늘리면 어느 크기든
+            오히려 줄었다. 큰 레코드(1KB 급)는 1개로도 디스크가 먼저 한계에 닿고, 작은 레코드(100B 급)는 4개
+            근처가 최대다.
 
         Example::
 

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/jetstream_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.7.0
+Version: 0.7.2
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -54,6 +54,28 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.7.2 변경 - batchSize 기본값 262144 로 되돌림, 발행 경로 CPU 절감 (자바 v2.3.2 와 같음)
+
+- `batchSize` 기본값을 **262144** 로 되돌렸습니다. 0.7.1 의 16384 에서 파이썬 클라는 처리량이 24~35% 낮았습니다(GIL 이
+  천장이라 배치마다 드는 비용이 그대로 처리량에서 빠집니다). 멱등 기본 켜짐은 그대로입니다.
+- 발행 경로 CPU 를 줄였습니다(API 는 그대로입니다). 레코드 future 가 배치 결과 하나를 함께 가리키고(완결은 배치당 한 번),
+  키 -> 파티션 결과를 캐시하고, `send()` 가 설정값을 레코드마다 다시 읽지 않고, I/O 스레드를 깨우는 신호를 합치고,
+  ACK 하나의 배치 완결을 잠금 한 번에 묶습니다.
+- producer 는 만들 때 설정 객체를 **복사**합니다(자바 v2.3.2 도 같고, Kafka 와 같습니다). 만든 뒤 넘긴 객체를 바꿔도 그
+  producer 에는 반영되지 않습니다 - 설정을 바꾸려면 producer 를 새로 만드십시오.
+- 문서: 멱등이 거르는 것은 producer 안의 재전송뿐입니다 - 앱이 `send` 를 다시 부르면 새 레코드로 적재됩니다.
+
+## 0.7.1 변경 - producer 기본값: 멱등 켜짐, batchSize 16384 (자바 v2.3.1 과 같음)
+
+- `enableIdempotence` 기본값이 **켜짐**입니다. 멱등을 직접 정하지 않았으면 `acks(0)` 이나 `maxInFlight` 가 5 를 넘을 때
+  멱등이 저절로 꺼집니다. `enableIdempotence(True)` 를 명시하고 그 둘과 함께 쓰면 전처럼 생성 때 `ValueError` 입니다.
+- 멱등이면 토픽을 비우거나(FLUSH) epoch 가 바뀐 순간 걸려 있던 배치를 다시 보내지 않고 실패로 올립니다
+  (`MIMQE_TOPIC_FLUSHED` / `MIMQE_TOPIC_EPOCH_MISMATCH`). 0.7.0 기본처럼 조용히 다시 보내려면 `enableIdempotence(False)` 를
+  명시하십시오.
+- `batchSize` 기본값이 **16384** 입니다(파티션 배치 하나의 상한). 0.7.0 은 262144 였습니다 - 처리량이 모자라면
+  `batchSize(262144)` 처럼 늘리십시오.
+- producer 수 안내: 한 토픽의 producer(연결)는 1~4개면 충분합니다(엔진 7.0.1.3407 실측).
+
 ## 0.7.0 변경 - 발행 v2: producer 하나 = 토픽 하나, 파티션별 배치, 봉투 겹쳐 보내기 (엔진 v2 필요)
 
 발행 경로를 엔진의 새 발행 형식(v2)으로 바꿨습니다. **엔진도 v2 판이어야 합니다** - 옛 엔진에는 발행이 되지 않고
@@ -61,7 +83,8 @@ pip install jetstream-api
 
 - **producer 하나 = 토픽 하나 = 연결 하나.** `qmgr.create_producer("ORDER.EVENT", config)` 로 만듭니다. 생성할 때 토픽의
   파티션 수를 받아 두므로 없는 토픽이면 생성 단계에서 `MIMQE_OBJECT_NOT_FOUND` 로 실패합니다. 토픽이 여러 개면 토픽마다
-  producer 를 만들고, 연결이 더 필요하면 producer 를 더 만듭니다(예: 발행 스레드마다 하나).
+  producer 를 만듭니다. 한 토픽의 producer(연결)는 1~4개면 충분합니다 - 엔진 7.0.1.3407 실측에서 8개로 늘리면 어느 크기든
+  오히려 줄었습니다. 큰 레코드(1KB 급)는 1개로도 디스크가 먼저 한계에 닿고, 작은 레코드(100B 급)는 4개 근처가 최대입니다.
 - 레코드 토픽이 producer 토픽과 다르면 `send()` 가 `MIMQE_INVALID_ARGUMENT` 로 거부합니다.
 - 옛 `create_producer(config)` / `ILTopicProducer(host, port, name, config)` 모양으로 부르면 `TypeError` 가 납니다.
 - 배치는 **파티션마다** 모입니다. `batchSize`(기본 **262144**, 자바와 같음)는 파티션 배치 하나의 상한입니다. 보낼 때는

{jetstream_api-0.7.0 → jetstream_api-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jetstream-api"
-version = "0.7.0"
+version = "0.7.2"
 description = "Python client API for iLink M.O.M. (Message Oriented Middleware)"
 authors = [{name = "snowjeans"}]
 readme = "README.md"