Added another example. [Bug 1216074]

2 files changed, 42 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 4d8c0e1..6a6a319 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,7 @@
 2009-01-30  Donal K. Fellows  <dkf@users.sf.net>
 
+	* doc/chan.n: [Bug 1216074]: Added another extended example.
+
 	* doc/refchan.n: Added an example of how to build a scripted channel.
 
 2009-01-29  Donal K. Fellows  <dkf@users.sf.net>
diff --git a/doc/chan.n b/doc/chan.n
index d79c717..2924465 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: chan.n,v 1.22 2008/10/15 10:43:37 dkf Exp $
+'\" RCS: @(#) $Id: chan.n,v 1.23 2009/01/30 11:34:36 dkf Exp $
 .so man.macros
 .TH chan n 8.5 Tcl "Tcl Built-In Commands"
 .BS
@@ -733,7 +733,8 @@ named \fIchannelId\fR to be \fIlength\fR (or to the current byte
 offset within the underlying data stream if \fIlength\fR is
 omitted). The channel is flushed before truncation.
 .
-.SH EXAMPLE
+.SH EXAMPLES
+.PP
 This opens a file using a known encoding (CP1252, a very common encoding
 on Windows), searches for a string, rewrites that part, and truncates the
 file after a further two lines.
@@ -766,6 +767,43 @@ while {[\fBchan gets\fR $f line] >= 0} {
 }
 \fBchan close\fR $f
 .CE
+.PP
+A network server that does echoing of its input line-by-line without
+preventing servicing of other connections at the same time.
+.PP
+.CS
+# This is a very simple logger...
+proc log {message} {
+    \fBchan puts\fR stdout $message
+}
+
+# This is called whenever a new client connects to the server
+proc connect {chan host port} {
+    set clientName [format <%s:%d> $host $port]
+    log "connection from $clientName"
+    \fBchan configure\fR $chan -blocking 0 -buffering line
+    \fBchan event\fR $chan readable [list echoLine $chan $clientName]
+}
+
+# This is called whenever either at least one byte of input
+# data is available, or the channel was closed by the client.
+proc echoLine {chan clientName} {
+    \fBchan gets\fR $chan line
+    if {[\fBchan eof\fR $chan]} {
+        log "finishing connection from $clientName"
+        \fBchan close\fR $chan
+    } elseif {![\fBchan blocked\fR $chan]} {
+        # Didn't block waiting for end-of-line
+        log "$clientName - $line"
+        \fBchan puts\fR $chan $line
+    }
+}
+
+# Create the server socket and enter the event-loop to wait
+# for incoming connections...
+socket -server connect 12345
+vwait forever
+.CE
 .SH "SEE ALSO"
 close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n),
 fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n),