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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.7.2
+Version: 0.7.3
 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,59 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.7.3 변경 - 구독마다 전용 연결, 소비 프로토콜 v5, 발행 / 소비 CPU 절감 (자바 v2.3.4 와 같음)
+
+- **엔진 요구**: 토픽 구독은 **엔진 7.0.1.3415 이상**(소비 프로토콜 v5)에서만 동작합니다. 그보다 옛 엔진은 요청 태그를
+  모르므로 구독 연결을 끊습니다. 발행과 큐 기능은 영향이 없습니다.
+- **구독마다 전용 연결**: 구독(패턴 구독이면 패턴 하나)마다 엔진 세션을 하나 따로 엽니다(클라이언트 이름 `<이름>-SUB`).
+  한 구독이 레코드를 기다려도 다른 구독이나 같은 `ILQmgr` 의 큐 / 관리 요청이 기다리지 않습니다. 대신 큐 관리자의 세션
+  수가 구독 수만큼 늘어납니다. 구독을 `close()` 하면 그 세션이 닫히고(엔진은 곧바로 멤버를 빼고 재배정합니다),
+  `ILQmgr.disconnect()` 는 그 세션에서 만든 구독을 모두 닫으며, `reconnect()` 는 구독 세션도 함께 다시 붙입니다.
+  `close()` 뒤의 read / commit 은 오류입니다. 다른 스레드의 read 가 레코드를 기다리던 중에 `close()` 하면 그 read 도 곧바로
+  끝납니다.
+- **`close()` 와 `unsubscribe()` 의 차이**: `close()` 는 **이 멤버만** 빠집니다(연결을 끊으면 엔진이 곧바로 멤버를 빼고 재배정하며,
+  커서는 남습니다). `unsubscribe()` 는 **구독(그룹) 자체를 지웁니다** - 모든 파티션의 커서(durable 포함)가 사라지고, 같은
+  구독 이름으로 붙어 있는 다른 멤버(다른 프로세스 포함)도 다음 read 에서 `MIMQE_TOPIC_SUBSCRIPTION_NOT_FOUND` 를 받습니다.
+  구독을 없앨 때만 부르세요. `unsubscribe()` 는 `close()` 뒤에도 됩니다(`ILQmgr` 의 연결로 보냅니다).
+  구독 세션은 `ILQmgr` 의 세션 모드와 상관없이 **늘 자동 확인 모드**로 열립니다 - 토픽 read / commit / seek 는 원래 세션
+  트랜잭션에 묶이지 않으므로(`qmgr.commit()` / `rollback()` 은 큐만 다룹니다) 동작은 그대로입니다.
+- **소비 프로토콜 v5**: 구독 연결의 요청에 태그를 붙여 겹쳐 보냅니다 - 레코드를 기다리는 동안에도 같은 구독의
+  commit / seek 가 곧바로 처리됩니다(한 구독의 read 는 하나씩 나갑니다). 패턴 구독은 매칭된 토픽 전체를 요청 한 번(다중 토픽
+  read)으로 받습니다. 커밋 좌표는 파티션 수와 관계없이 **한 요청**에 실리고, 한 요청 전체가 되거나 안 되거나입니다 - 이 멤버에게
+  배정되지 않은 파티션이 하나라도 있으면 `MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)` 로 아무것도
+  커밋되지 않습니다.
+
+- **정확성**:
+  - 한 `ILQmgr` 에서 `listen()` 구독이 둘 이상이거나, `listen()` 중에 같은 `ILQmgr` 로 다른 요청(큐 put/get, 관리 요청,
+    다른 구독의 read)을 하면 소켓 하나에서 요청과 응답이 섞일 수 있었습니다. 이제 연결마다 잠금 하나로 요청-응답을 짝 단위로
+    줄 세웁니다(먼저 기다린 쪽이 먼저).
+  - `listen()` 콜백이 예외를 던져 멈추면, 뒤이은 `close()` 가 처리하지 않은 레코드까지 AUTO 커밋하던 결함을 고쳤습니다.
+    이제 콜백이 정상으로 끝난 레코드만 커밋 대상이고, 콜백하지 못한 레코드는 같은 핸들의 다음 read / listen 이 다시 줍니다.
+  - `seek_to_offset(offset, partition)` 이 **다른 파티션**의 받아 두기만 한 레코드와 AUTO 커밋 좌표까지 버리던 결함을
+    고쳤습니다(0.7.2 에도 있었습니다). 엔진은 지정한 파티션만 되감으므로 버려진 다른 파티션 구간은 다시 오지 않았고, AUTO 는
+    뒤 커밋이 그 구간을 건너뛰었습니다. 이제 지정한 파티션만 버리고, seek 응답보다 먼저 도착한(곧 seek 전 위치에서 읽은) 그
+    파티션의 레코드는 앱에 주지 않습니다. `partition` 을 생략하면 엔진은 **0번 파티션 하나만** 되감습니다(`offset=0` 이어도
+    구독 전체가 아닙니다). 예전에는 이때도 모든 파티션의 받아 둔 레코드를 버렸습니다 - 이제 `;partition:0` 을 붙여 보내고 0번
+    것만 버립니다. `seek_to_time()` 은 전 파티션을 되감으므로 전부 버립니다.
+  - seek 는 엔진이 멤버를 보지 않고 커서를 옮깁니다. 이 멤버에게 배정된 파티션만 되감고(`get_assignment()`), `seek_to_time()` 은
+    그룹에 멤버가 하나일 때만 쓰세요.
+  - `close()` 의 AUTO 커밋이 `MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)` 로 거절되면 그 파티션을 빼고
+    다시 보냅니다 - 아직 소유한 파티션의 좌표는 반영됩니다(예전에는 전부 버려져 다음 멤버에게 다시 갔습니다).
+- **문서**: 세션 목록(`ILSessionProperty`)의 `destroyedTime` 은 살아 있는 세션에서 **-1** 입니다(0 이 아닙니다). 끊긴 세션은
+  끊긴 시각(epoch 밀리초)입니다. 살아 있는지는 `status` 로 판정하세요.
+- **발행 CPU**: `send()` 가 레코드를 배치 버퍼에 곧바로 붙이고, 잠금 / 파티션 선택 / 키 인코딩 비용을 줄였습니다(레코드당 약 30% 감소).
+- **소비 CPU**: 저장 v4 배치 응답을 풀면서 레코드 객체를 바로 만들고, AUTO 커밋 병합을 파티션마다 한 번 합니다(`read_batch` 약 40% 감소).
+- **소비 왕복**:
+  - `read()` 가 AUTO / MANUAL 에서 prefetch 건수(기본 500)까지 한 번에 받아 두고 차례로 줍니다(레코드마다 왕복하지 않습니다).
+    IMMEDIATE 는 지금처럼 1건씩 요청합니다. 받아 두기만 한 레코드는 커밋되지 않으며, AUTO 커밋은 다음 요청(또는 `close()`)에 실립니다.
+  - `commit(list)` / `close()` 가 파티션마다 가장 큰 오프셋을 모아 파티션 수와 관계없이 한 요청으로 커밋합니다.
+  - `listen()` 과 prefetch 기본 배치가 100 에서 500 이 됐습니다.
+- **패턴 구독**: `read` / `read_batch` 한 번이 매칭된 토픽 전체를 다중 토픽 read 요청 하나로 묻습니다. 한 토픽이라도 레코드가
+  있으면 곧바로 돌아오고, 모두 비었으면 `timeout_ms` 동안 어느 토픽이든 들어오기를 기다립니다 - 한가한 토픽이 많아도 바쁜 토픽이
+  늦어지지 않습니다. 한 번에 토픽 하나가 가져가는 양은 `bufferPerTopic` 으로 묶고, 시작 토픽을 호출마다 한 칸씩 돌립니다(바쁜
+  토픽이 셋 이상일 때 하나를 건너뛰던 결함을 고쳤습니다). 목록 `commit` 은 토픽마다 한 요청이며, 보내기 전에 전부 검사합니다
+  (출처가 없는 레코드가 있으면 아무것도 커밋하지 않습니다).
+
 ## 0.7.2 변경 - batchSize 기본값 262144 로 되돌림, 발행 경로 CPU 절감 (자바 v2.3.2 와 같음)
 
 - `batchSize` 기본값을 **262144** 로 되돌렸습니다. 0.7.1 의 16384 에서 파이썬 클라는 처리량이 24~35% 낮았습니다(GIL 이