jetstream-api 0.10.0__tar.gz → 0.11.0__tar.gz

{jetstream_api-0.10.0 → jetstream_api-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.10.0
+Version: 0.11.0
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -60,6 +60,52 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.11.0 변경 - 큐 단건 put / get 가속, `commit_and_get` 추가
+
+- **새 API `ILQueue.commit_and_get(matchId=None, option=MatchOption.NONE)`** (camelCase 별칭 `commitAndGet`): 이 세션의
+  미확정 작업을 커밋하고 이어서 다음 메시지를 꺼냅니다. `qmgr.commit()` 뒤에 `q.get()` 을 부른 것과 결과가 같고, 커밋
+  요청과 get 요청을 응답을 기다리지 않고 연달아 보내므로 **1 왕복**입니다(따로 부르면 2 왕복).
+  **get → commit 을 반복하는 소비 루프는 반드시 commit_and_get 을 쓴다.** 확정 시점은 그대로(처리를 마치고 부르는 순간)입니다.
+
+  ```python
+  q = qmgr.access_queue("APP.REQUEST.Q")      # 트랜잭션 세션
+  try:
+      msg = q.get()
+      while True:
+          process(msg)
+          msg = q.commit_and_get()            # 처리한 것을 확정하고 다음 것을 꺼낸다 - 1 왕복
+  except ILNoMsgException:
+      pass                                    # 마지막 커밋은 이미 끝났다
+  ```
+
+  - 대기 시간 안에 메시지가 없으면 `ILNoMsgException` 입니다 - **이때도 커밋은 이미 성공했습니다.** 커밋한 메시지 수는
+    돌려주지 않습니다(필요하면 `commit()` 을 따로 부릅니다).
+  - 커밋이 실패하면 `commit()` 과 같은 `ILOperationException` 입니다. 커밋 뒤에 보낸 get 이 꺼낸 메시지는 롤백으로 큐에
+    되돌린 뒤 올립니다. 커밋은 됐는데 get 을 엔진이 거절하면 `get()` 과 같은 예외입니다.
+  - 커밋 요청을 보낸 뒤 커밋 응답 전에 연결이 끊기면 커밋 결과를 알 수 없으므로 **자동 재접속 / 재시도 없이**
+    `ILSessionException` 입니다(`commit()` 과 같습니다). 커밋이 성공한 뒤의 get 장애는 `get()` 처럼 자동 재접속 후 1회
+    재시도합니다.
+  - 자동 커밋 세션이면 커밋 요청 없이 `get()` 과 똑같습니다. 무한 대기(`set_wait_msg_timeout_ms(-1)`)도 `get()` 과 같습니다.
+- **와이어 형식은 그대로입니다.** 5.x / 6.x / 7.x 엔진 모두에서 씁니다. 연달아 보내기는 한 세션의 요청을 받은 순서대로
+  처리하고 그 순서로 답하는 것이 확인된 엔진(7.x, 그리고 6.3.x 중 6.3.3 부터)에서만 하고, 그 밖의 엔진(5.x 등, 판을 읽지
+  못한 경우 포함)에서는 커밋 응답을 받은 뒤 get 을 보냅니다(2 왕복, 결과는 같습니다).
+- **내부 가속 - 공개 API 변화는 `commit_and_get` 추가뿐입니다.** 보내는 바이트는 0.10.0 과 같습니다(옛 판과 바이트 대조 시험).
+  - put 프레임을 한 번에 조립합니다(본문 복사 한 번). JMS 헤더 / 응답 칸은 한 번에 풉니다.
+  - 받기: 연결마다 수신 버퍼에 `recv_into` 로 받고, 소켓 timeout 은 값이 바뀔 때만 줍니다. 큰 get 응답은 본문을 한 번만
+    복사합니다(`getData()` 는 여전히 호출자 소유의 `bytes`).
+  - COMMIT / ROLLBACK 요청 프레임과 큐 핸들의 GET 요청 프레임을 짜 두고 씁니다(대기 시간 / 선택자가 바뀌면 다시 짭니다).
+  - 트랜잭션 세션의 put(프레임 64KiB 이하)은 곧바로 보내지 않고 이 연결의 다음 요청(보통 `commit()`)과 한 번에 보냅니다.
+    요청 순서 처리가 확인된 엔진(7.x, 6.3.3 부터)에서만 그렇게 하고, 그 밖의 엔진에는 0.10.0 과 같이 곧바로 보냅니다.
+    그래서 **연결 오류가 put 이 아니라 그 다음 요청에서 드러납니다.** `rollback()` 은 아직 보내지 않은 put 을 ROLLBACK 과
+    한 번에 보냅니다(돌려주는 값은 0.10.0 과 같습니다). 연결이 닫힌 것을 이미 알면 예전처럼 put 에서 바로 실패합니다. NIO 커넥터
+    (`set_conn(TCPConnectorNIO())`)는 묶어 보내지 않습니다.
+  - `client_name` 을 비운 `connect()` 의 호출 모듈 이름 판별이 가벼워졌습니다(결과는 같습니다).
+- **put 이 채우는 msgId**: 여전히 uuid4 모양(36자, 소문자 16진)이지만 `random` 모듈의 128비트로 만듭니다. 유일 식별자이지
+  **보안 토큰이 아닙니다** - 예측할 수 없어야 하면 msgId 를 직접 지정하세요. fork 한 자식 프로세스는 `random` 이 다시
+  시드되므로 부모와 같은 값을 내지 않습니다.
+- **사용 안내**: 큐 핸들은 한 번 얻어 계속 씁니다(메시지마다 `access_queue()` 를 부르면 존재 확인 왕복이 한 번씩 더 듭니다 -
+  존재를 이미 알면 `access_queue(name, exist_check=False)`). `ILQmgr` 는 스레드마다 따로 둡니다.
+
 ## 0.10.0 변경 - 토픽 레코드 v5: 길이 칸 varint (자바 v2.6.0 과 같음)
 
 - **레코드 v5**: producer 가 파티션 배치를 magic 5 로 씁니다. 레코드의 길이 칸 셋(key / 속성 / 값)이 4바이트 고정에서