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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.7.1
+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,17 @@ 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 를 넘을 때

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

@@ -8,6 +8,17 @@ 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 를 넘을 때

{jetstream_api-0.7.1 → 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.1"
+__version__ = "0.7.2"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser

{jetstream_api-0.7.1 → 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,9 +63,9 @@ class ILProducerConfig:
         self._acks = 1
         #: 배치를 모으는 시간(ms). 0 이면 모이는 대로 즉시 보낸다
         self._lingerMs = 0
-        # 0.7.1: Kafka batch.size 와 같은 16384(사용자 결정 2026-09-13). 0.7.0 은 262144 였다
-        #: 파티션 배치 하나의 크기 상한(바이트). 기본 16384
-        self._batchSize = 16384
+        # 0.7.2: 262144 로 되돌렸다(사용자 결정 2026-09-13). 0.7.1 의 16384 에서 24~35% 느렸다(GIL 천장)
+        #: 파티션 배치 하나의 크기 상한(바이트). 기본 262144
+        self._batchSize = 262144
         #: 동시에 ACK 를 기다릴 봉투 수 상한
         self._maxInFlight = 5
         #: 연결 실패 시 재시도 횟수
@@ -135,7 +140,7 @@ class ILProducerConfig:
         self._lingerMs = max(0, n); return self
 
     def batchSize(self, n: int) -> "ILProducerConfig":
-        """파티션 배치 하나의 크기 상한(바이트)을 정한다. (기본 16384 = 16KB)
+        """파티션 배치 하나의 크기 상한(바이트)을 정한다. (기본 262144 = 256KB)
 
         Args:
             n (int): 상한(**바이트**). 배치는 파티션마다 따로 모인다. 레코드를 붙이면 이 값을
@@ -145,7 +150,8 @@ class ILProducerConfig:
             ILProducerConfig: 체이닝을 위해 자기 자신.
 
         Note:
-            뜻과 기본값이 Java 클라이언트와 같다(0.7.1 부터 16384. 0.7.0 은 262144 였다 - 처리량이 모자라면 늘린다).
+            뜻과 기본값이 Java 클라이언트와 같다(0.7.2 에서 262144 로 되돌렸다. 0.7.1 은 16384 였고 파이썬은
+            그 값에서 24~35% 느렸다).
             ``lingerMs`` 가 0 이면 자르는 크기로만 쓰이고(배치는 보낼 수 있게 되는 즉시 나간다),
             ``lingerMs`` 가 0 보다 크면 전송 조건도 된다(이만큼 차거나 lingerMs 가 지나면 보낸다).
             레코드 하나가 이 값보다 크면 그 레코드 혼자 배치 하나가 된다. 보낼 때는 준비된
@@ -194,8 +200,10 @@ class ILProducerConfig:
             보낸다(순서 유지). 재시도 총 시간은 :meth:`deliveryTimeoutMs` 로도 함께 제한된다.
 
         Warning:
-            재시도는 **중복 적재를 만들 수 있다.** ACK 를 못 받은 것과 서버가 적재를
-            못 한 것은 구분되지 않는다. 중복이 곤란하면 :meth:`enableIdempotence`.
+            비멱등(``enableIdempotence(False)``)이면 재시도는 **중복 적재를 만들 수 있다.** ACK 를
+            못 받은 것과 서버가 적재를 못 한 것은 구분되지 않는다. 멱등(기본 켜짐)이면 producer 안의
+            재시도는 엔진이 걸러 한 번만 적재된다. 앱이 ``send`` 를 다시 부르는 재발행은 새 레코드라
+            멱등이어도 걸러지지 않는다.
         """
         self._retries = max(0, n); return self
 
@@ -321,7 +329,8 @@ class ILProducerConfig:
         """멱등 발행(중복 제거)을 켜거나 끈다. (기본 켜짐 - 0.7.1)
 
         켜면 접속 시 서버에서 PID 를 발급받아 파티션 배치마다 (PID, baseSeq) 를 실어 보낸다.
-        재시도로 같은 배치가 두 번 도착해도 서버가 시퀀스로 걸러 **한 번만 적재한다.**
+        재시도로 같은 배치가 두 번 도착해도 서버가 시퀀스로 걸러 **한 번만 적재한다.** 걸러지는 것은
+        producer 안의 재시도뿐이다 - 앱이 ``send`` 를 다시 부르면 새 레코드로 적재된다.
         ``maxInFlight`` 는 5 이하여야 한다.
 
         이 메서드로 정하지 않으면 ``acks=0`` 이거나 ``maxInFlight`` 가 5 를 넘을 때 멱등이 저절로 꺼진다.
@@ -422,10 +431,10 @@ class ILProducerConfig:
         return self._lingerMs
 
     def get_batch_size(self) -> int:
-        """파티션 배치 하나의 크기 상한(바이트). 기본 16384.
+        """파티션 배치 하나의 크기 상한(바이트). 기본 262144.
 
         Returns:
-            int: 파티션 배치 하나의 크기 상한(바이트). 기본 16384.
+            int: 파티션 배치 하나의 크기 상한(바이트). 기본 262144.
         """
         return self._batchSize
 
@@ -742,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:
         """발행이 끝날 때까지 기다렸다가 좌표를 돌려준다.
@@ -788,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:
         """완결(성공이든 실패든)되었는지.
@@ -801,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**.
@@ -958,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
@@ -1032,8 +1092,9 @@ class ILTopicProducer:
     - **순서**: 한 파티션 안에서는 ``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 부터 다시 매긴다.
@@ -1059,7 +1120,8 @@ 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 의
@@ -1081,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
@@ -1098,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)
@@ -1134,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
@@ -1288,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:
@@ -1378,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:
@@ -1415,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
@@ -1432,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
@@ -1468,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
@@ -1477,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
 
@@ -1596,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:
@@ -1607,6 +1697,8 @@ class ILTopicProducer:
                 pass
         except OSError:
             pass
+        # 비운 뒤에 내린다. 먼저 내리면 비우는 사이 온 신호를 먹고도 표시가 올라간 채 남아 다음 깨우기가 막힐 수 있다
+        self._wake_pending = False
 
     def _wake_waiters(self) -> None:
         with self._cv:
@@ -1965,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)
@@ -2082,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.1 → 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 16KB / maxInFlight 5 / 멱등 켜짐).
+                기본값(acks=1 / linger 0 / batch 256KB / maxInFlight 5 / 멱등 켜짐).
 
         Returns:
             ILTopicProducer: 발행자. 다 쓰면 ``close()`` 로 닫는다.

{jetstream_api-0.7.1 → 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.1
+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,17 @@ 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 를 넘을 때

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

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