transchan

Обработчик преобразования канала на уровне Tcl должен быть командой с подкомандами (называемыми *ансамблем*, несмотря на то, что это не подразумевает, что он должен быть создан с помощью namespace ensemble create; этот механизм никак не связан с namespace ensemble). Обратите внимание, что cmdPrefix — это то, что было указано при вызове chan push, и может состоять из нескольких аргументов; это будет расширено до нескольких слов вместо префикса.

Из всех возможных подкоманд обработчик *должен* поддерживать initialize и finalize. Преобразования для записываемых каналов также должны поддерживать write, а преобразования для читаемых каналов также должны поддерживать read.

Обратите внимание, что в описаниях ниже cmdPrefix может быть более чем одним словом, а handle — значение, возвращаемое вызовом chan push, используемым для создания преобразования.

Общие подкоманды

Следующие подкоманды относятся ко всем типам каналов.

cmdPrefix clear handle

Эта необязательная подкоманда вызывается для того, чтобы сообщить преобразованию, что любые данные, хранящиеся во внутренних буферах (входящие или исходящие), должны быть очищены. Она вызывается при выполнении chan seek для преобразуемого канала.

cmdPrefix finalize handle

Эта обязательная подкоманда вызывается последней для данного handle и больше никогда не вызывается, и она существует для того, чтобы позволить очистить любые данные Tcl-уровня, связанные с преобразованием. Предупреждение! Любые ошибки, выброшенные этой подкомандой, будут проигнорированы. Гарантируется ли вызов этой подкоманды при удалении интерпретатора не гарантируется.

cmdPrefix initialize handle mode

Эта обязательная подкоманда вызывается первой и больше никогда не вызывается (для данного handle). Она отвечает за инициализацию всех частей преобразования на уровне Tcl. mode — это список, содержащий любой из элементов read и write.

write: означает, что канал записываемый.
read: означает, что канал читаемый.

Возвращаемое значение подкоманды должно быть списком, содержащим имена всех подкоманд, поддерживаемых этим обработчиком. Любая ошибка, выброшенная подкомандой, предотвратит создание преобразования. Выброшенная ошибка будет отображаться как ошибка, выброшенная chan push.

Подкоманды, связанные с чтением

Эти подкоманды используются для обработки преобразований, применяемых к читаемым каналам; хотя строго read необязательно, она должна поддерживаться, если любая из других подкоманд поддерживается, иначе канал станет нечитаемым.

cmdPrefix drain handle: Эта необязательная подкоманда вызывается всякий раз, когда данные во входном буфере преобразования (т.е. чтение) должны быть принудительно переданы вверх, т.е. к пользователю или скрипту. Результат, возвращаемый методом, принимается в качестве бинарных данных для передачи вверх на уровень выше этого преобразования (читателю или преобразованию более высокого уровня).
Другими словами, когда этот метод вызывается, преобразование не может больше откладывать фактическую операцию преобразования и должно преобразовать все данные, ожидающие в его внутренних буферах чтения, и вернуть результат этого действия.
cmdPrefix limit? handle: Эта необязательная подкоманда вызывается для того, чтобы позволить Tcl I/O-движку определить, насколько далеко вперед следует читать. Если она присутствует, она должна вернуть целое число, большее нуля, которое указывает, на сколько байтов вперед следует читать, или целое число, меньшее нуля, чтобы указать, что I/O-движок может читать так далеко вперед, как захочет.
cmdPrefix read handle buffer: Эта подкоманда, которая должна присутствовать, если преобразование должно работать с читаемыми каналами, вызывается всякий раз, когда базовый канал или преобразование ниже этого преобразования передает данные вверх. buffer содержит бинарные данные, которые были нам предоставлены снизу. Эта подкоманда отвечает за фактическое преобразование данных. Возвращаемый результат подкоманды принимается в качестве бинарных данных для дальнейшей передачи вверх к преобразованию выше этого преобразования. Это также может быть пользователь или скрипт, который первоначально читал из канала.
Обратите внимание, что результат может быть пустым или даже меньше данных, которые мы получили; преобразование не обязано преобразовывать все данные, предоставленные ему прямо сейчас. Ему разрешено хранить входящие данные во внутренних буферах и откладывать фактическое преобразование до тех пор, пока у него не будет больше данных.

Подкоманды, связанные с записью

Эти подкоманды используются для обработки преобразований, применяемых к записываемым каналам; хотя строго write необязательно, она должна поддерживаться, если любая из других подкоманд поддерживается, иначе канал станет незаписываемым.

cmdPrefix flush handle: Эта необязательная подкоманда вызывается всякий раз, когда данные в буфере преобразования «запись» должны быть принудительно переданы вниз, т.е. к базовому каналу. Возвращаемый результат подкоманды принимается в качестве бинарных данных для записи в преобразование ниже текущего преобразования. Это также может быть базовый канал.
Другими словами, при вызове этой подкоманды преобразование не может отложить фактическую операцию преобразования и должно преобразовать все данные, ожидающие в его внутренних буферах записи, и вернуть результат этого действия.
cmdPrefix write handle buffer: Эта подкоманда, которая должна присутствовать, если преобразование должно работать с записываемыми каналами, вызывается всякий раз, когда пользователь или преобразование выше этого преобразования записывает данные вниз. buffer содержит бинарные данные, которые были записаны нам. Эта подкоманда отвечает за фактическое преобразование данных.
Возвращаемый результат подкоманды принимается в качестве бинарных данных для записи в преобразование ниже этого преобразования. Это также может быть базовый канал. Обратите внимание, что результат может быть пустым или меньше полученных данных; преобразование не обязано преобразовывать все, что было ему записано прямо сейчас. Ему разрешено хранить эти данные во внутренних буферах и откладывать фактическое преобразование до тех пор, пока у него не будет больше данных.

См. также

chan, refchan

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/transchan.htm