* doc/chan.n: Updated with documentation for the commands 'chan

	  create' and 'chan postevent' (TIP #219).

	* doc/refchan.n: New file. Documentation of the command handler
	  API for reflected channels (TIP #219).

1 files changed, 278 insertions, 0 deletions

diff --git a/doc/refchan.n b/doc/refchan.n
new file mode 100644
index 0000000..a35ec53
--- /dev/null
+++ b/doc/refchan.n
@@ -0,0 +1,278 @@
+'\" 
+'\" Copyright (c) 2006 Andreas Kupries
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" RCS: @(#) $Id: refchan.n,v 1.1 2006/03/17 17:24:10 andreas_kupries Exp $
+.so man.macros
+.TH reflectedchan n 8.5 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+reflectedchan \- Command handler API of reflected channels, version 1
+.SH SYNOPSIS
+\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The Tcl-level handler for a reflected channel has to be a command with
+subcommands (termed an \fIensemble\fR, as it is a command such as that
+created by \fBnamespace ensemble create\fR, though the implementation
+of handlers for reflected channel \fIis not\fR tied to \fBnamespace
+ensemble\fRs in any way). Note that \fIcmdPrefix\fR is whatever was
+specified in the call to \fBchan create\fR, and may consist of
+multiple arguments; this will be expanded to multiple words in place
+of the prefix.
+.PP
+Of all the possible subcommands, the handler \fImust\fR support
+\fBinitialize\fR, \fBfinalize\fR, and \fBwatch\fR. Support for the
+other subcommands is optional.
+.SS "MANDATORY SUBCOMMANDS"
+.TP
+\fIcmdPrefix \fBinitialize \fIchannel mode\fR
+.
+An invokation of this subcommand will be the first call the
+\fIcmdPrefix\fR will receive for the specified new \fBchannel\fR. It
+is the responsibility of this subcommand to set up any internal data
+structures required to keep track of the channel and its state.
+.RS
+.PP
+The return value of the method has to be a list containing the names
+of all subcommands supported by the \fIcmdPrefix\fR. This also tells
+the Tcl core which version of the API for reflected channels is used by
+this command handler.
+.PP
+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 \fBchan create\fR. Any exception other than an \fBerror\fR
+(e.g. \fBbreak\fR, etc.) is treated as (and converted to) an error.
+.PP
+\fBNote:\fR If the creation of the channel was aborted due to failures
+here, then the \fBfinalize\fR subcommand will not be called.
+.PP
+The \fImode\fR argument tells the handler whether the channel was
+opened for reading, writing, or both. It is a list containing any of
+the strings "\fBread\fR" or "\fBwrite\fR". The list will always
+contain at least one element.
+.PP
+The subcommand must throw an error if the chosen mode is not
+supported by the \fIcmdPrefix\fR.
+.RE
+.TP
+\fIcmdPrefix \fBfinalize \fIchannel\fR
+.
+An invokation of this subcommand will be the last call the
+\fIcmdPrefix\fR will receive for the specified \fIchannel\fR. It will
+be generated just before the destruction of the data structures of the
+channel held by the Tcl core. The command handler \fImust not\fR
+access the \fIchannel\fR anymore in no way. Upon this subcommand being
+called, any internal resources allocated to this channel must be
+cleaned up.
+.RS
+.PP
+The return value of this subcommand is ignored.
+.PP
+If the subcommand throws an error the command which caused its
+invocation (usually \fBclose\fR) will appear to have thrown this
+error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is
+treated as (and converted to) an error.
+.PP
+This subcommand is not invoked if the creation of the channel was
+aborted during \fBinitialize\fR (See above).
+.RE
+.TP
+\fIcmdPrefix \fBwatch \fIchannel eventspec\fR
+.
+This subcommand notifies the \fIcmdPrefix\fR that the specified
+\fIchannel\fR is interested in the events listed in the
+\fIeventspec\fR. This argument is a list containing any of "\fBread\fR"
+and "\fBwrite\fR". 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.
+.RS
+.PP
+\fBWarning:\fR Any return value of the subcommand is ignored. This
+includes all errors thrown by the subcommand, break, continue, and
+custom return codes.
+.PP
+This subcommand interacts with \fBchan postevent\fR. Trying to post an
+event which was not listed in the last call to \fBwatch\fR will cause
+\fBchan postenvent\fR to throw an error.
+.RE
+.SS "OPTIONAL SUBCOMMANDS"
+.TP
+\fIcmdPrefix \fBread \fIchannel count\fR
+.
+This \fIoptional\fR subcommand is called when the user requests data
+from a channel. \fIcount\fR specifies how many \fBbytes\fR have been
+requested. If the subcommand is not supported then it is not possible
+to read from the channel handled by the command.
+.RS
+.PP
+The return value of this subcommand is taken as the requested data
+\fIbytes\fR. If the returned data contains more bytes than requested,
+an error will be signalled and later thrown by the command which
+performed the read (usually \fBgets\fR or \fBread\fR). However,
+returning fewer bytes than requested is acceptable.
+.PP
+If the subcommand throws an error, the command which caused its
+invocation (usually \fBgets\fR, or \fBread\fR) will appear to have
+thrown this error. Any exception beyond \fIerror\fR, (e.g.
+\fIbreak\fR, etc.) is treated as and converted to an error.
+.RE
+.TP
+\fIcmdPrefix \fBwrite \fIchannel data\fR
+.
+This \fIoptional\fR subcommand is called when the user writes data to
+the channel. The \fIdata\fR argument contains \fIbytes\fR, not
+characters. Any type of transformation (EOL, encoding) configured 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.
+.RS
+.PP
+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 performed 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.
+.PP
+If the subcommand throws an error the command which caused its
+invocation (usually \fBputs\fR) will appear to have thrown this error.
+Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated
+as and converted to an error.
+.RE
+.TP
+\fIcmdPrefix \fBseek \fIchannel offset base\fR
+.
+This \fIoptional\fR subcommand is responsible for the handling of
+\fBseek\fR and \fBtell\fR requests on the channel. If it is not
+supported then seeking will not be possible for the channel.
+.RS
+.PP
+The \fIbase\fR argument is one of
+.TP 10
+\fBstart\fR
+.
+Seeking is relative to the beginning of the channel.
+.TP 10
+\fBcurrent\fR
+.
+Seeking is relative to the current seek position.
+.TP 10
+\fBend\fR
+.
+Seeking is relative to the end of the channel.
+.PP
+The \fIbase\fR argument of the builtin \fBchan seek\fR command takes
+the same names.
+.PP
+The \fIoffset\fR is an integer number specifying the amount of
+\fBbytes\fR to seek forward or backward. A positive number should seek
+forward, and a negative number should seek backward.
+.PP
+A channel may provide only limited seeking. For example sockets can
+seek forward, but not backward.
+.PP
+The return value of the subcommand is taken as the (new) location of
+the channel, counted from the start. This has to be an integer number
+greater than or equal to zero.
+.PP
+If the subcommand throws an error the command which caused its
+invocation (usually \fBseek\fR, or \fBtell\fR) will appear to have
+thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR,
+etc.) is treated as and converted to an error.
+.PP
+The offset/base combination of 0/"\fBcurrent\fR" signals a \fBtell\fR
+request, i.e. seek nothing relative to the current location, making
+the new location identical to the current one, which is then returned.
+.RE
+.TP
+\fIcmdPrefix \fBconfigure \fIchannel option value\fR
+.
+This \fIoptional\fR subcommand is for writing the type specific
+options. The \fIoption\fR argument indicates the option to be written,
+and the \fIvalue\fR argument indicates the value to set the option to.
+.RS
+.PP
+This subcommand will never try to update more than one option at a
+time; that is behavior implemented in the Tcl channel core.
+.PP
+The return value of the subcommand is ignored.
+.PP
+If the subcommand throws an error the command which performed the
+(re)configuration or query (usually \fBfconfigure\fR or \fBchan
+configure\fR) will appear to have thrown this error. Any exception
+beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and
+converted to an error.
+.RE
+.TP
+\fIcmdPrefix \fBcget \fIchannel option\fR
+.
+This \fIoptional\fR subcommand is used when reading a single type
+specific option. If this subcommand is supported then the subcommand
+\fBcgetall\fR must be supported as well.
+.RS
+.PP
+The subcommand should return the value of the specified \fIoption\fR.
+.PP
+If the subcommand throws an error, the command which performed the
+(re)configuration or query (usually \fBfconfigure\fR) will appear to
+have thrown this error. Any exception beyond \fIerror\fR (e.g.
+\fIbreak\fR, etc.) is treated as and converted to an error.
+.RE
+.TP
+\fIcmdPrefix \fBcgetall \fIchannel\fR
+.
+This \fIoptional\fR subcommand is used for reading all type specific
+options. If this subcommand is supported then the subcommand
+\fBcget\fR has to be supported as well.
+.RS
+.PP
+The subcommand should return a list of all options and their values.
+This list must have an even number of elements.
+.PP
+If the subcommand throws an error the command which performed the
+(re)configuration or query (usually \fBfconfigure\fR) will appear to
+have thrown this error. Any exception beyond \fIerror\fR (e.g.
+\fIbreak\fR, etc.) is treated as and converted to an error.
+.RE
+.TP
+\fIcmdPrefix \fBblocking \fIchannel mode\fR
+.
+This \fIoptional\fR subcommand handles changes to the blocking mode of
+the channel. The \fImode\fR 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.
+.RS
+.PP
+The return value of the subcommand is ignored.
+.PP
+If the subcommand throws an error the command which caused its
+invocation (usually \fBfconfigure\fR) will appear to have thrown this
+error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is
+treated as and converted to an error.
+.RE
+.SH NOTES
+Some of the functions supported in channels defined in Tcl's C
+interface are not available to channels reflected to the Tcl level.
+.PP
+The function \fBTcl_DriverGetHandleProc\fR is not supported; i.e.
+reflected channels do not have OS specific handles.
+.PP
+The function \fBTcl_DriverHandlerProc\fI is not supported. This driver
+function is relevant only for stacked channels, i.e. transformations.
+Reflected channels are always base channels, not transformations.
+.PP
+The function \fBTcl_DriverFlushProc\fR 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.
+.SH "SEE ALSO"
+chan(n)
+.SH KEYWORDS
+channel, reflection