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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.7.2
+Version: 0.7.4
 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,94 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.7.4 변경 - 패턴 토픽 떼어 내기 = 그룹 탈퇴(LEAVE), seek 규칙 (자바 v2.3.5 와 같음)
+
+- **엔진 요구**: 아래 새 동작은 **엔진 7.0.1.3417 이상**(CONSGRP-1)에서 나옵니다. 그보다 옛 엔진에서는 그룹 탈퇴 요청을 조용히
+  건너뛰고(예전처럼 패턴 구독을 닫을 때까지 멤버로 남습니다), 파티션을 생략한 `seek_to_offset()` 은 0번 파티션을 되감습니다.
+  클라이언트는 엔진 판을 따로 검사하지 않습니다.
+- **패턴 구독 - 떼어 낸 토픽은 그룹에서 빠집니다**: 재평가로 더 이상 매칭되지 않거나 read 중 오류로 떼어 낸 토픽은 그 (토픽, 구독)
+  그룹에서 이 세션을 뺍니다(`MIMQ_TOPIC_LEAVE` = 3401). 엔진이 곧바로 재배정하므로 같은 구독 이름의 다른 멤버가 그 파티션을
+  이어받고, 커서는 남습니다. 예전에는 연결을 닫지 않으니 패턴 구독을 닫을 때까지 멤버로 남아 그 파티션을 아무도 읽지 않았습니다.
+  그 토픽이 실린 다중 토픽 read 가 엔진에 걸려 있는 동안은 보내지 않고(엔진이 `MIMQE_READ_IN_PROGRESS` 로 거절합니다) 그 read 가
+  돌아온 직후 / 다음 read 전에 보냅니다 - 다른 스레드의 `refresh_now()` 는 걸린 read 를 기다리지 않고 돌아옵니다. best-effort 라
+  실패(구독 없음, 옛 엔진, 통신 실패)는 앱에 올리지 않습니다. 패턴 `close()` / `unsubscribe()` 와 단일 토픽 구독의 `close()` 는
+  그대로입니다(연결을 닫으면 엔진이 멤버를 뺍니다).
+- **seek 는 이 멤버에게 배정된 파티션만**: 배정 밖 파티션이면 `ILOperationException`
+  (`MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)`) 입니다. 재배정 통지가 아니라 거절이라 받아 둔 레코드는
+  그대로이고 다시 보내지 않습니다. 아직 read 하지 않은 구독은 그룹에 멤버가 하나도 없을 때만 seek 할 수 있습니다 - "subscribe →
+  seek → read" 는 혼자일 때만 되고, 다른 멤버가 있으면 첫 read 로 배정 통지를 받은 뒤(예: `set_rebalance_listener()` 콜백 안)
+  seek 하세요. `assign()` 구독은 배정 목록 밖 파티션이면 `(Partition : N not in manual assignment)` 사유로 거절됩니다. 관리 연결
+  (`ILAdminTopicSubscription`)의 seek 는 그룹에 멤버가 없을 때만 됩니다.
+- **`seek_to_offset(offset)` - 파티션 생략은 엔진이 정합니다**: 0.7.3 은 생략하면 `;partition:0` 을 붙였습니다. 이제 `offset:N`
+  그대로 보냅니다. 새 엔진은 파티션이 하나인 토픽에서만 받고, 다중 파티션 토픽이면 `MIMQE_INVALID_ARGUMENT (Partition : REQUIRED,
+  Available : 0~N)` 로 거절합니다 - **다중 파티션 토픽에서는 `partition` 을 주세요.** 옛 엔진은 0번 파티션을 되감습니다. 성공하면
+  받아 둔 레코드는 0번 파티션 것만 버리고, 거절되면 아무것도 버리지 않습니다.
+- **`seek_to_time(epoch_ms, partition=-1)`** (`seekToTime(epochMs, partition)`): 파티션을 줄 수 있습니다(`time:T;partition:P`,
+  받아 둔 레코드도 P 것만 버립니다). 새 엔진은 이 멤버에게 배정된 파티션만 옮기고(파티션을 주면 그 파티션만), 돌려주는 값은 옮긴
+  파티션 중 번호가 가장 작은 파티션의 결과 오프셋입니다(옮긴 것이 없으면 -1). 옛 엔진은 파티션을 무시하고 구독 전체를 옮기며
+  0번 파티션의 결과를 줍니다 - 옛 엔진에서는 파티션을 주지 마세요.
+- **문서**: `ILAdminTopicSubscription.seek_to_offset()` 의 "`-1` 이면 전 파티션" 은 틀린 설명이었습니다(엔진은 0번 파티션만
+  되감았습니다).
+- **NIO 커넥터(`TCPConnectorNIO`)도 송수신이 실패하면 연결을 닫습니다**(기본 커넥터와 같게): 전에는 큰 프레임을 받다가 시간이 다하면
+  나머지가 소켓에 남은 채 연결이 살아 있어 같은 연결의 다음 요청이 그 조각부터 읽었고(`invalid transmission delimiter`), 자동 확인
+  GET 이면 그 메시지를 잃었습니다. 상대가 프레임 중간에 끊으면 끝없이 돌던 것도 곧바로 `MIMQE_NIO_ERROR` 로 끝나고, 기한이 지났어도
+  소켓에 다 와 있는 프레임은 돌려주며, 보낼 자리가 없을 때(`BlockingIOError`) 곧바로 실패하던 송신은 기다렸다 이어 보냅니다. 기본
+  (블로킹) 커넥터에서도 프레임 중간에 시간이 다한 자동 확인 GET 의 메시지는 잃습니다(최대 한 번 전달) - 아주 큰 메시지는 GET 대기
+  시간 / 세션 시간 초과를 넉넉히 주거나 트랜잭션 GET(`auto_commit=False` 세션 + `commit()`)을 쓰세요.
+
+## 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 이

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

@@ -8,6 +8,94 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.7.4 변경 - 패턴 토픽 떼어 내기 = 그룹 탈퇴(LEAVE), seek 규칙 (자바 v2.3.5 와 같음)
+
+- **엔진 요구**: 아래 새 동작은 **엔진 7.0.1.3417 이상**(CONSGRP-1)에서 나옵니다. 그보다 옛 엔진에서는 그룹 탈퇴 요청을 조용히
+  건너뛰고(예전처럼 패턴 구독을 닫을 때까지 멤버로 남습니다), 파티션을 생략한 `seek_to_offset()` 은 0번 파티션을 되감습니다.
+  클라이언트는 엔진 판을 따로 검사하지 않습니다.
+- **패턴 구독 - 떼어 낸 토픽은 그룹에서 빠집니다**: 재평가로 더 이상 매칭되지 않거나 read 중 오류로 떼어 낸 토픽은 그 (토픽, 구독)
+  그룹에서 이 세션을 뺍니다(`MIMQ_TOPIC_LEAVE` = 3401). 엔진이 곧바로 재배정하므로 같은 구독 이름의 다른 멤버가 그 파티션을
+  이어받고, 커서는 남습니다. 예전에는 연결을 닫지 않으니 패턴 구독을 닫을 때까지 멤버로 남아 그 파티션을 아무도 읽지 않았습니다.
+  그 토픽이 실린 다중 토픽 read 가 엔진에 걸려 있는 동안은 보내지 않고(엔진이 `MIMQE_READ_IN_PROGRESS` 로 거절합니다) 그 read 가
+  돌아온 직후 / 다음 read 전에 보냅니다 - 다른 스레드의 `refresh_now()` 는 걸린 read 를 기다리지 않고 돌아옵니다. best-effort 라
+  실패(구독 없음, 옛 엔진, 통신 실패)는 앱에 올리지 않습니다. 패턴 `close()` / `unsubscribe()` 와 단일 토픽 구독의 `close()` 는
+  그대로입니다(연결을 닫으면 엔진이 멤버를 뺍니다).
+- **seek 는 이 멤버에게 배정된 파티션만**: 배정 밖 파티션이면 `ILOperationException`
+  (`MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)`) 입니다. 재배정 통지가 아니라 거절이라 받아 둔 레코드는
+  그대로이고 다시 보내지 않습니다. 아직 read 하지 않은 구독은 그룹에 멤버가 하나도 없을 때만 seek 할 수 있습니다 - "subscribe →
+  seek → read" 는 혼자일 때만 되고, 다른 멤버가 있으면 첫 read 로 배정 통지를 받은 뒤(예: `set_rebalance_listener()` 콜백 안)
+  seek 하세요. `assign()` 구독은 배정 목록 밖 파티션이면 `(Partition : N not in manual assignment)` 사유로 거절됩니다. 관리 연결
+  (`ILAdminTopicSubscription`)의 seek 는 그룹에 멤버가 없을 때만 됩니다.
+- **`seek_to_offset(offset)` - 파티션 생략은 엔진이 정합니다**: 0.7.3 은 생략하면 `;partition:0` 을 붙였습니다. 이제 `offset:N`
+  그대로 보냅니다. 새 엔진은 파티션이 하나인 토픽에서만 받고, 다중 파티션 토픽이면 `MIMQE_INVALID_ARGUMENT (Partition : REQUIRED,
+  Available : 0~N)` 로 거절합니다 - **다중 파티션 토픽에서는 `partition` 을 주세요.** 옛 엔진은 0번 파티션을 되감습니다. 성공하면
+  받아 둔 레코드는 0번 파티션 것만 버리고, 거절되면 아무것도 버리지 않습니다.
+- **`seek_to_time(epoch_ms, partition=-1)`** (`seekToTime(epochMs, partition)`): 파티션을 줄 수 있습니다(`time:T;partition:P`,
+  받아 둔 레코드도 P 것만 버립니다). 새 엔진은 이 멤버에게 배정된 파티션만 옮기고(파티션을 주면 그 파티션만), 돌려주는 값은 옮긴
+  파티션 중 번호가 가장 작은 파티션의 결과 오프셋입니다(옮긴 것이 없으면 -1). 옛 엔진은 파티션을 무시하고 구독 전체를 옮기며
+  0번 파티션의 결과를 줍니다 - 옛 엔진에서는 파티션을 주지 마세요.
+- **문서**: `ILAdminTopicSubscription.seek_to_offset()` 의 "`-1` 이면 전 파티션" 은 틀린 설명이었습니다(엔진은 0번 파티션만
+  되감았습니다).
+- **NIO 커넥터(`TCPConnectorNIO`)도 송수신이 실패하면 연결을 닫습니다**(기본 커넥터와 같게): 전에는 큰 프레임을 받다가 시간이 다하면
+  나머지가 소켓에 남은 채 연결이 살아 있어 같은 연결의 다음 요청이 그 조각부터 읽었고(`invalid transmission delimiter`), 자동 확인
+  GET 이면 그 메시지를 잃었습니다. 상대가 프레임 중간에 끊으면 끝없이 돌던 것도 곧바로 `MIMQE_NIO_ERROR` 로 끝나고, 기한이 지났어도
+  소켓에 다 와 있는 프레임은 돌려주며, 보낼 자리가 없을 때(`BlockingIOError`) 곧바로 실패하던 송신은 기다렸다 이어 보냅니다. 기본
+  (블로킹) 커넥터에서도 프레임 중간에 시간이 다한 자동 확인 GET 의 메시지는 잃습니다(최대 한 번 전달) - 아주 큰 메시지는 GET 대기
+  시간 / 세션 시간 초과를 넉넉히 주거나 트랜잭션 GET(`auto_commit=False` 세션 + `commit()`)을 쓰세요.
+
+## 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 이

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

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

{jetstream_api-0.7.2 → jetstream_api-0.7.4}/ilink/admin.py

@@ -6,7 +6,7 @@ import time
 import uuid
 
 from .common import ILC, ILRC, MatchOption
-from .connectivity import ILRequestHelper
+from .connectivity import ILRequestHelper, _io_lock_of
 from .exception import (
     UnsupportedOperationException,
     ILException,
@@ -5250,7 +5250,6 @@ class ILAdminQmgr:
                 str(self.waitMsgTimeoutMS),
             )
             while True:
-                self.service.getConn().send(req_msg)
                 timeout = self.service.getSessionTimeout()
                 if (
                     not self.isInfiniteWaiting
@@ -5259,7 +5258,11 @@ class ILAdminQmgr:
                 ):
                     timeout = self.waitMsgTimeoutMS * 2
 
-                msg = self.service.getConn().recv(timeout)
+                # 0.7.3: 요청-응답 짝을 연결 잠금 안에서(무한 대기면 회차마다 놓는다)
+                conn = self.service.getConn()
+                with _io_lock_of(conn):
+                    conn.send(req_msg)
+                    msg = conn.recv(timeout)
                 if msg.getType() == ILC.MIMQ_DATA_MESSAGE:
                     return msg.getDataMsg()
 

{jetstream_api-0.7.2 → jetstream_api-0.7.4}/ilink/admintopic.py

@@ -103,6 +103,12 @@ class ILAdminTopicSubscription:
         삼키고 같은 조건으로 한 번 더 요청하므로 호출부는 신경 쓸 것이 없다.
         배정 내역을 보고 싶으면 :meth:`get_last_assignment`.
 
+    .. note:: seek 는 빈 그룹에서만 (엔진 7.0.1.3417 이상)
+
+        관리 연결의 :meth:`seek_to_offset` / :meth:`seek_to_time` 은 그 구독(그룹)에 멤버가 하나도 없을 때만 된다.
+        데이터 연결로 읽는 멤버가 있으면 ``MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)`` 로
+        거절된다 - 그때는 그 멤버가 자기 구독 핸들로 seek 한다.
+
     Example::
 
         from ilink.exception import ILNoMsgException
@@ -308,11 +314,18 @@ class ILAdminTopicSubscription:
 
         Args:
             offset (int): 다음에 읽을 오프셋.
-            partition (int): 대상 파티션. ``-1``(기본)이면 전 파티션.
+            partition (int): 대상 파티션. ``-1`` (기본)이면 생략 - 파티션 없이 ``offset:N`` 으로 보내고 판단은 엔진에
+                맡긴다. **전 파티션이 아니다.** 다중 파티션 토픽에서는 반드시 준다.
 
         Raises:
-            ILOperationException: 서버가 거절했을 때.
+            ILOperationException: 서버가 거절했을 때. 그룹에 멤버가 있으면
+                ``MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)``, 다중 파티션 토픽에서
+                ``partition`` 을 생략하면 ``MIMQE_INVALID_ARGUMENT (Partition : REQUIRED, Available : 0~N)``.
             ILException: 통신 실패.
+
+        Warning:
+            엔진 7.0.1.3417 이상에서는 그 구독(그룹)에 **멤버가 하나도 없을 때만** 된다. ``partition`` 을 생략한 seek 는
+            파티션이 하나인 토픽에서만 받는다. 그보다 옛 엔진은 생략하면 거절하지 않고 **0번 파티션 하나만** 되감는다.
         """
         self._seek("offset:%d" % offset, None if partition < 0 else partition)
 
@@ -323,11 +336,16 @@ class ILAdminTopicSubscription:
             epoch_ms (int): 기준 시각(**epoch 밀리초**).
 
         Returns:
-            int: 서버가 정한 새 오프셋.
+            int: 서버가 정한 새 오프셋. 엔진 7.0.1.3417 이상은 옮긴 파티션 중 번호가 가장 작은 파티션의 결과이고
+            (옮긴 것이 없으면 ``-1``), 옛 엔진은 0번 파티션의 결과다.
 
         Raises:
-            ILOperationException: 서버가 거절했을 때.
+            ILOperationException: 서버가 거절했을 때. 그룹에 멤버가 있으면
+                ``MIMQE_TOPIC_REBALANCED (partition N is not owned by this member)``.
             ILException: 통신 실패.
+
+        Warning:
+            엔진 7.0.1.3417 이상에서는 그 구독(그룹)에 **멤버가 하나도 없을 때만** 된다.
         """
         return self._seek("time:%d" % epoch_ms, None)
 

{jetstream_api-0.7.2 → jetstream_api-0.7.4}/ilink/common.py

@@ -260,6 +260,13 @@ class ILC:
     #: 발행 v2 ACK. corrId + 봉투 code / 사유 + 배치 수 + 배치마다 {partition, code, baseOffset, timestamp,
     #: expectedSeq, 사유}. 봉투 헤더를 못 읽으면 봉투 code / 사유만 싣고 배치 수 0 이다.
     MIMQ_TOPIC_PUBLISH_V2_ACK_MESSAGE = 2041
+    #: 0.7.3 소비 프로토콜 v5(엔진 CONSV5-1): 요청 태그. 본문 ``[u16 1][i64 corrId]`` - 요청 바로 앞에 보내면 응답 바로 앞에
+    #: 같은 태그가 온다(응답 순서는 요청 순서와 다를 수 있다). 큐 PUT/GET, 트랜잭션, 발행에 달면 엔진이 연결을 끊는다.
+    MIMQ_REQ_TAG_MESSAGE = 2044
+    #: 0.7.3 다중 토픽 read 요청 / 응답(이진 BE). 응답 절 = 토픽, 구독, 상태(0 데이터 / 2 재배정 / 3 오류), 사유, 2042 본문.
+    #: 모든 항목이 비어 시간이 다하면 2046 대신 REPORT(``MIMQ_NO_NEW_MESSAGE``)가 온다.
+    MIMQ_TOPIC_FETCH_MULTI_MESSAGE = 2045
+    MIMQ_TOPIC_FETCH_MULTI_RESP_MESSAGE = 2046
     MIMQ_LONG_REQUEST_CODE_LENGTH = 6
     MIMQ_LONG_REQUEST_ARG_LENGTH = 70
     MIMQ_LIST_ITEM_COUNT_LENGTH = 5
@@ -454,6 +461,11 @@ class ILC:
     #: arg2=epoch. 실패 4157 이면 arg2=사유(없는 토픽은 MIMQE_OBJECT_NOT_FOUND, flush 창이면
     #: MIMQE_TOPIC_FLUSHED - 재시도할 수 있다). 데이터 연결과 관리 연결 릴레이 둘 다 받는다.
     MIMQ_TOPIC_METADATA = 3397
+    #: 0.7.4 CONSGRP-1(엔진 r3417): 이 세션을 (토픽, 구독) 그룹에서 뺀다. arg1=토픽, arg2=구독, arg3="". 곧바로
+    #: 재배정하고 커서는 남긴다. 성공 4156 이면 arg1 "1"(뺐다) / "0"(멤버가 아니었다). 구독이 없으면 4157
+    #: SUBSCRIPTION_NOT_FOUND, 그 (토픽, 구독)에 read 가 걸려 있으면(태그 롱폴 / FETCH_MULTI 항목) 4157
+    #: MIMQE_READ_IN_PROGRESS. 다시 read 하면 다시 든다(재배정 통지부터). r3416 이하 엔진은 모르는 요청으로 거절한다.
+    MIMQ_TOPIC_LEAVE = 3401
 
     # 토픽 응답 코드
     MIMQ_SUCCESSFUL_TOPIC_OPERATION = 4156