refchan(n) Tcl Built-In Commands refchan(n)______________________________________________________________________________NAMErefchan - Command handler API of reflected channels, version 1
SYNOPSIS
cmdPrefix option ?arg arg ...?
_________________________________________________________________DESCRIPTION
The Tcl-level handler for a reflected channel has to be a command with
subcommands (termed an ensemble, as it is a command such as that cre‐
ated by namespace ensemble create, though the implementation of han‐
dlers for reflected channel is not tied to namespace ensembles in any
way). Note that cmdPrefix is whatever was specified in the call to chan
create, and may consist of multiple arguments; this will be expanded to
multiple words in place of the prefix.
Of all the possible subcommands, the handler must support initialize,
finalize, and watch. Support for the other subcommands is optional.
MANDATORY SUBCOMMANDS
cmdPrefix initialize channelId mode
An invocation of this subcommand will be the first call the cmd‐
Prefix will receive for the specified new channelId. It is the
responsibility of this subcommand to set up any internal data
structures required to keep track of the channel and its state.
The return value of the method has to be a list containing the
names of all subcommands supported by the cmdPrefix. This also
tells the Tcl core which version of the API for reflected chan‐
nels is used by this command handler.
Any error thrown by the method will abort the creation of the
channel and no channel will be created. The thrown error will
appear as error thrown by chan create. Any exception other than
an error (e.g. break, etc.) is treated as (and converted to) an
error.
Note: If the creation of the channel was aborted due to failures
here, then the finalize subcommand will not be called.
The mode argument tells the handler whether the channel was
opened for reading, writing, or both. It is a list containing
any of the strings read or write. The list will always contain
at least one element.
The subcommand must throw an error if the chosen mode is not
supported by the cmdPrefix.
cmdPrefix finalize channelId
An invocation of this subcommand will be the last call the cmd‐
Prefix will receive for the specified channelId. It will be gen‐
erated just before the destruction of the data structures of the
channel held by the Tcl core. The command handler must not
access the channelId anymore in no way. Upon this subcommand
being called, any internal resources allocated to this channel
must be cleaned up.
The return value of this subcommand is ignored.
If the subcommand throws an error the command which caused its
invocation (usually close) will appear to have thrown this
error. Any exception beyond error (e.g. break, etc.) is treated
as (and converted to) an error.
This subcommand is not invoked if the creation of the channel
was aborted during initialize (See above).
cmdPrefix watch channelId eventspec
This subcommand notifies the cmdPrefix that the specified chan‐
nelId is interested in the events listed in the eventspec. This
argument is a list containing any of read and write. The list
may be empty, which signals that the channel does not wish to be
notified of any events. In that situation, the handler should
disable event generation completely.
Warning: Any return value of the subcommand is ignored. This
includes all errors thrown by the subcommand, break, continue,
and custom return codes.
This subcommand interacts with chan postevent. Trying to post an
event which was not listed in the last call to watch will cause
chan postevent to throw an error.
OPTIONAL SUBCOMMANDS
cmdPrefix read channelId count
This optional subcommand is called when the user requests data
from the channel channelId. count specifies how many bytes have
been requested. If the subcommand is not supported then it is
not possible to read from the channel handled by the command.
The return value of this subcommand is taken as the requested
data bytes. If the returned data contains more bytes than
requested, an error will be signaled and later thrown by the
command which performed the read (usually gets or read). How‐
ever, returning fewer bytes than requested is acceptable.
Note that returning nothing (0 bytes) is a signal to the higher
layers that EOF has been reached on the channel. To signal that
the channel is out of data right now, but has not yet reached
EOF, it is necessary to throw the error "EAGAIN", i.e. to either
return -code error EAGAIN
or
error EAGAIN
For extensibility any error whose value is a negative integer
number will cause the higher layers to set the C-level variable
"errno" to the absolute value of this number, signaling a system
error. This means that both
return -code error -11
and
error -11
are equivalent to the examples above, using the more readable
string "EAGAIN". No other error value has such a mapping to a
symbolic string.
If the subcommand throws any other error, the command which
caused its invocation (usually gets, or read) will appear to
have thrown this error. Any exception beyond error, (e.g.
break, etc.) is treated as and converted to an error.
cmdPrefix write channelId data
This optional subcommand is called when the user writes data to
the channel channelId. The data argument contains bytes, not
characters. Any type of transformation (EOL, encoding) config‐
ured for the channel has already been applied at this point. If
this subcommand is not supported then it is not possible to
write to the channel handled by the command.
The return value of the subcommand is taken as the number of
bytes written by the channel. Anything non-numeric will cause an
error to be signaled and later thrown by the command which per‐
formed the write. A negative value implies that the write
failed. Returning a value greater than the number of bytes given
to the handler, or zero, is forbidden and will cause the Tcl
core to throw an error.
To signal that the channel is not able to accept data for writ‐
ing right now, it is necessary to throw the error "EAGAIN", i.e.
to either
return -code error EAGAIN
or
error EAGAIN
For extensibility any error whose value is a negative integer
number will cause the higher layers to set the C-level variable
"errno" to the absolute value of this number, signaling a system
error. However, note that the exact mapping between these error
numbers and their meanings is operating system dependent.
For example, while on Linux both
return -code error -11
and
error -11
are equivalent to the examples above, using the more readable
string "EAGAIN", this is not true for BSD, where the equivalent
number is -35.
The symbolic string however is the same across systems, and
internally translated to the correct number. No other error
value has such a mapping to a symbolic string.
If the subcommand throws any other error the command which
caused its invocation (usually puts) will appear to have thrown
this error. Any exception beyond error (e.g. break, etc.) is
treated as and converted to an error.
cmdPrefix seek channelId offset base
This optional subcommand is responsible for the handling of seek
and tell requests on the channel channelId. If it is not sup‐
ported then seeking will not be possible for the channel.
The base argument is one of
start Seeking is relative to the beginning of the channel.
current Seeking is relative to the current seek position.
end Seeking is relative to the end of the channel.
The base argument of the builtin chan seek command takes the
same names.
The offset is an integer number specifying the amount of bytes
to seek forward or backward. A positive number should seek for‐
ward, and a negative number should seek backward.
A channel may provide only limited seeking. For example sockets
can seek forward, but not backward.
The return value of the subcommand is taken as the (new) loca‐
tion of the channel, counted from the start. This has to be an
integer number greater than or equal to zero.
If the subcommand throws an error the command which caused its
invocation (usually seek, or tell) will appear to have thrown
this error. Any exception beyond error (e.g. break, etc.) is
treated as and converted to an error.
The offset/base combination of 0/current signals a tell request,
i.e. seek nothing relative to the current location, making the
new location identical to the current one, which is then
returned.
cmdPrefix configure channelId option value
This optional subcommand is for setting the type-specific
options of channel channelId. The option argument indicates the
option to be written, and the value argument indicates the value
to set the option to.
This subcommand will never try to update more than one option at
a time; that is behavior implemented in the Tcl channel core.
The return value of the subcommand is ignored.
If the subcommand throws an error the command which performed
the (re)configuration or query (usually fconfigure or chan con‐
figure) will appear to have thrown this error. Any exception
beyond error (e.g. break, etc.) is treated as and converted to
an error.
cmdPrefix cget channelId option
This optional subcommand is used when reading a single type-spe‐
cific option of channel channelId. If this subcommand is sup‐
ported then the subcommand cgetall must be supported as well.
The subcommand should return the value of the specified option.
If the subcommand throws an error, the command which performed
the (re)configuration or query (usually fconfigure) will appear
to have thrown this error. Any exception beyond error (e.g.
break, etc.) is treated as and converted to an error.
cmdPrefix cgetall channelId
This optional subcommand is used for reading all type-specific
options of channel channelId. If this subcommand is supported
then the subcommand cget has to be supported as well.
The subcommand should return a list of all options and their
values. This list must have an even number of elements.
If the subcommand throws an error the command which performed
the (re)configuration or query (usually fconfigure) will appear
to have thrown this error. Any exception beyond error (e.g.
break, etc.) is treated as and converted to an error.
cmdPrefix blocking channelId mode
This optional subcommand handles changes to the blocking mode of
the channel channelId. The mode is a boolean flag. A true value
means that the channel has to be set to blocking, and a false
value means that the channel should be non-blocking.
The return value of the subcommand is ignored.
If the subcommand throws an error the command which caused its
invocation (usually fconfigure) will appear to have thrown this
error. Any exception beyond error (e.g. break, etc.) is treated
as and converted to an error.
NOTES
Some of the functions supported in channels defined in Tcl's C inter‐
face are not available to channels reflected to the Tcl level.
The function Tcl_DriverGetHandleProc is not supported; i.e. reflected
channels do not have OS specific handles.
The function Tcl_DriverHandlerProc is not supported. This driver func‐
tion is relevant only for stacked channels, i.e. transformations.
Reflected channels are always base channels, not transformations.
The function Tcl_DriverFlushProc is not supported. This is because the
current generic I/O layer of Tcl does not use this function anywhere at
all. Therefore support at the Tcl level makes no sense either. This may
be altered in the future (through extending the API defined here and
changing its version number) should the function be used at some time
in the future.
SEE ALSOchan(n)KEYWORDS
channel, reflection
Tcl 8.5 refchan(n)
