Tcl Tutorial Lesson 42

More channel I/O - fblocked and fconfigure

The previous lessons have shown how to use channels with files and blocking sockets. Tcl also supports non-blocking reads and writes, and allows you to configure the sizes of the I/O buffers, and how lines are terminated.

A non-blocking read or write means that instead of a gets call waiting until data is available, it will return immediately. If there was data available, it will be read, and if no data is available, the gets call will return a 0 length.

If you have several channels that must be checked for input, you can use the fileevent command to trigger reads on the channels, and then use the fblocked command to determine when all the data is read.

The fblocked and fconfigure commands provide more control over the behavior of a channel.

The fblocked command checks whether a channel has returned all available input. It is useful when you are working with a channel that has been set to non-blocking mode and you need to determine if there should be data available, or if the channel has been closed from the other end.

The fconfigure command has many options that allow you to query or fine tune the behavior of a channel including whether the channel is blocking or non-blocking, the buffer size, the end-of-line character, etc.

fconfigure channel ?param1? ?value1? ?param2 value2 ...?
Configures the behavior of a channel. If no param values are provided, a list of the valid configuration parameters and their values is returned.

If a single parameter is given on the command line, the value of that parameter is returned.

If one or more pairs of param/value pairs are provided, those parameters are set to the requested value.

Parameters that can be set include:

  • -blocking - determines whether or not the task will block when data cannot be moved on a channel (i.e. if no data is available on a read, or the buffer is full on a write).
  • -buffersize - the number of bytes that will be buffered before data is sent, or can be buffered before being read when data is received. The value must be an integer between 10 and 1000000.
  • -translation - sets how Tcl will terminate a line when it is output. By default, the lines are terminated with the newline, carriage return, or newline/carriage return that is appropriate to the system on which the interpreter is running. This can be configured to be:
    • auto - translates newline, carriage return, or newline/carriage return as an end of line marker. Outputs the correct line termination for the current platform.
    • binary - treats newlines as any other character. Does not add any line termination to lines being output. The file or channel is treated as binary.
    • cr - treats carriage returns as the end of line marker (and translates them to newline internally). Output lines are terminated with a carriage return. This is the Apple standard.
    • crlf - treats cr/lf pairs as the end of line marker, and terminates output lines with a carriage return/linefeed combination. This is the Windows standard, and should also be used for all line-oriented network protocols.
    • lf - treats linefeeds as the end of line marker, and terminates output lines with a linefeed. This is the UNIX/Linux standard.

The example below is similar to the example with a client and server socket. It shows a server channel being configured to be non-blocking, and using the default buffering style - data is not made available to the script until a newline is present, or the buffer has filled. When the first write:

   puts -nonewline $sock "A Test Line"`

is done, the fileevent triggers the read, but the gets can't read characters because there is no newline. The gets returns a -1, and fblocked returns a 1. When a bare newline is sent, the data in the input buffer will become available, and the gets returns 18, and fblocked returns 0.


Example

We expand the two auxiliary procs in example with a client and server socket, so that we get information about the state of the channel:

proc serverOpen {channel addr port} {
    puts "channel: $channel - from Address: $addr  Port: $port"
    puts "The default state for blocking is: \
[fconfigure $channel -blocking]"
    puts "The default buffer size is: \
[fconfigure $channel -buffersize]"

    # Set this channel to be non-blocking.
    fconfigure $channel -blocking 0
    set bl [fconfigure $channel -blocking]
    puts "After fconfigure the state for blocking is: $bl"

    # Change the buffer size to be smaller
    fconfigure $channel -buffersize 12
    puts "After fconfigure buffer size is: \
[fconfigure $channel -buffersize ]\n"

    # When input is available, read it.
    fileevent $channel readable "readLine Server $channel"
}

proc readLine {who channel} {
    global didRead
    global blocked

    puts "There is input for $who on $channel"

    set len [gets $channel line]
    set blocked [fblocked $channel]
    puts "Characters Read: $len  Fblocked: $blocked"

    if {$len < 0} {
        if {$blocked} {
            puts "Input is blocked"
        } else {
            puts "The socket was closed - closing my end"
            close $channel;
        }
    } else {
        puts "Read $len characters:  $line"
        puts $channel "This is a return"
        flush $channel;
    }
    incr didRead;
}

Now, start the server and send a few lines of text, while also manipulating the channel's state.

set server [socket -server serverOpen 33000]

after 120 update;       # This kicks Windows machines for this
                        # application ...

set sock [socket 127.0.0.1 33000]

set bl [fconfigure $sock -blocking]
set bu [fconfigure $sock -buffersize]
puts "Original settings: Sock blocking: $bl buffersize: $bu"

fconfigure $sock -blocking No
fconfigure $sock -buffersize 8;

set bl [fconfigure $sock -blocking]
set bu [fconfigure $sock -buffersize]
puts "Modified settings: Sock blocking: $bl buffersize: $bu\n"

# Send a line to the server -- NOTE flush

set didRead 0
puts -nonewline $sock "A Test Line"
flush $sock;

# Loop until two reads have been done.

while {$didRead < 2} {
    # Wait for didRead to be set
    vwait didRead
    if {$blocked} {
        puts $sock "Newline"
        flush $sock
        puts "SEND NEWLINE"
    }
}

set len [gets $sock line]
puts "Return line: $len -- $line"
close $sock
vwait didRead
catch {close $server}

  Resulting output
Original settings: Sock blocking: 1 buffersize: 4096
Modified settings: Sock blocking: 0 buffersize: 8

channel: sock0000000001D55EE0 - from Address: 127.0.0.1  Port: 6346
The default state for blocking is: 1
The default buffer size is: 4096
After fconfigure the state for blocking is: 0
After Fconfigure buffer size is: 12

There is input for Server on sock0000000001D55EE0
Characters Read: -1  Fblocked: 1
Input is blocked
SEND NEWLINE
There is input for Server on sock0000000001D55EE0
Characters Read: 18  Fblocked: 0
Read 18 characters:  A Test LineNewline
Return line: 16 -- This is a return
There is input for Server on sock0000000001D55EE0
Characters Read: -1  Fblocked: 0
The socket was closed - closing my end