transchan — 채널 변환의 명령 핸들러 API
transchan — 채널 변환의 명령 핸들러 API
Tcl 채널에 변환을 끼워 넣으면 데이터가 지나가는 길목에서 가공할 수 있어요. chan push로 만든 변환은 Tcl 레벨에서 서브컴마드가 있는 명령으로 구현되는데, 그 명령이 채워야 할 API를 설명하는 문서가 바로 이 문서예요.
본문
cmdPrefix option ?arg arg ...?
채널 변환의 Tcl 레벨 핸들러는 서브컴마드가 있는 명령이어야 해요. (이를 ensemble이라고 부르지만 namespace ensemble create로 만들어야 한다는 뜻은 아니에요. 이 메커니즘은 namespace ensemble과 전혀 관련이 없어요.) cmdPrefix는 chan push 호출에서 지정한 것이며 여러 인자로 이뤄질 수 있어요. 이는 접두어 자리에 여러 단어로 확장돼요.
가능한 모든 서브컴마드 중에서 핸들러는 반드시 initialize와 finalize를 지원해야 해요. 쓰기 가능한 채널의 변환은 반드시 write도 지원해야 하고, 읽기 가능한 채널의 변환은 반드시 read도 지원해야 해요.
아래 설명에서 cmdPrefix는 여러 단어일 수 있고, handle은 변환을 만들 때 사용한 chan push 호출이 반환한 값이에요.
일반 서브컴마드(Generic Subcommands)
다음 서브컴마드들은 모든 종류의 채널에 관련돼요.
cmdPrefix clear handle(선택): 내부 버퍼(들어오거나 나가는)에 저장된 데이터를 모두 지워야 한다는 것을 변환에 알리기 위해 호출돼요. 변환되는 채널에chan seek를 수행할 때 호출돼요.cmdPrefix finalize handle(필수): 주어진 핸들에 대해 마지막으로 호출되고, 그 후로는 다시 호출되지 않아요. 변환과 연관된 Tcl 레벨 데이터 구조를 정리하기 위해 존재해요. 주의! 이 서브컴마드가 던지는 오류는 무시돼요. 인터프리터가 삭제되면 호출이 보장되지 않아요.cmdPrefix initialize handle mode(필수): (주어진 핸들에 대해) 가장 먼저 호출되고 다시는 호출되지 않아요. Tcl 레벨에서 변환의 모든 부분을 초기화하는 책임이 있어요.mode는read와write를 포함하는 리스트예요.write: 채널이 쓰기 가능함을 뜻해요.read: 채널이 읽기 가능함을 뜻해요.
이 서브컴마드의 반환 값은 이 핸들러가 지원하는 모든 서브컴마드의 이름을 담은 리스트여야 해요. 이 서브컴마드가 던지는 오류는 변환 생성이 실패하게 해요. 그 오류는 chan push가 던지는 오류로 나타나요.
읽기 관련 서브컴마드(Read-Related Subcommands)
이 서브컴마드들은 읽기 가능한 채널에 적용된 변환을 처리하는 데 쓰여요. 엄밀히 read는 선택이지만, 다른 것 중 하나라도 지원하려면 반드시 지원해야 해요. 아니면 채널이 읽기 불가능해져요.
cmdPrefix drain handle(선택): 변환 입력(즉 read) 버퍼의 데이터를 위로, 즉 사용자나 스크립트 쪽으로 강제로 밀어 올려야 할 때마다 호출돼요. 메서드가 반환한 결과는 이 변환 위의 레벨(읽는 쪽이나 더 높은 변환)로 밀어 올릴 바이너리 데이터로 취급돼요. 다시 말해, 이 메서드가 호출되면 변환은 실제 변환 연산을 더 이상 미룰 수 없고, 내부 읽기 버퍼에 대기 중인 모든 데이터를 변환한 결과를 반환해야 해요.cmdPrefix limit? handle(선택): Tcl I/O 엔진이 얼마나 앞을 읽어야 하는지 결정하도록 허용하기 위해 호출돼요. 있으면, 얼마나 많은 바이트를 앞서 읽어야 하는지 나타내는 0보다 큰 정수를 반환하거나, I/O 엔진이 원하는 만큼 앞서 읽어도 된다는 뜻의 0보다 작은 정수를 반환해요.cmdPrefix read handle buffer(필수, 읽기 채널에서 작동하려면): 기본 채널이나 이 변환 아래의 변환이 데이터를 위로 밀어 올릴 때마다 호출돼요.buffer에는 아래에서 받은 바이너리 데이터가 들어 있어요. 이 서브컴마드가 실제로 데이터를 변환할 책임이 있어요. 반환 결과는 이 변환 위의 변환으로 더 밀어 올릴 바이너리 데이터로 취급돼요. 이는 원래 채널에서 읽은 사용자나 스크립트일 수도 있어요. 결과는 비어 있거나 받은 데이터보다 작아도 된다는 점에 주의하세요. 변환은 지금 받은 모든 것을 변환할 필요가 없어요. 들어오는 데이터를 내부 버퍼에 저장하고 더 많은 데이터가 있을 때까지 실제 변환을 미룰 수 있어요.
쓰기 관련 서브컴마드(Write-Related Subcommands)
이 서브컴마드들은 쓰기 가능한 채널에 적용된 변환을 처리하는 데 쓰여요. 엄밀히 write는 선택이지만, 다른 것 중 하나라도 지원하려면 반드시 지원해야 해요. 아니면 채널이 쓰기 불가능해져요.
cmdPrefix flush handle(선택): 변환의 'write' 버퍼에 있는 데이터를 아래로, 즉 기본 채널 쪽으로 강제로 밀어 내려야 할 때마다 호출돼요. 서브컴마드가 반환한 결과는 현재 변환 아래의 변환에 쓸 바이너리 데이터로 취급돼요. 기본 채널일 수도 있어요. 다시 말해, 이 서브컴마드가 호출되면 변환은 실제 변환 연산을 더 이상 미룰 수 없고, 내부 쓰기 버퍼에 대기 중인 모든 데이터를 변환한 결과를 반환해야 해요.cmdPrefix write handle buffer(필수, 쓰기 채널에서 작동하려면): 사용자나 이 변환 위의 변환이 데이터를 아래로 쓸 때마다 호출돼요.buffer에는 작성된 바이너리 데이터가 들어 있어요. 이 서브컴마드가 실제로 데이터를 변환할 책임이 있어요. 반환 결과는 이 변환 아래의 변환에 쓸 바이너리 데이터로 취급돼요. 기본 채널일 수도 있어요. 결과는 비어 있거나 받은 데이터보다 작아도 된다는 점에 주의하세요. 변환은 지금 작성된 모든 것을 변환할 필요가 없어요. 이 데이터를 내부 버퍼에 저장하고 더 많은 데이터가 있을 때까지 실제 변환을 미룰 수 있어요.