Provided by: tcl8.6-doc_8.6.13+dfsg-2_all bug

NAME

       refchan - command handler API of reflected channels

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 created by namespace ensemble create,  though
       the implementation of handlers for reflected channel is not tied to namespace ensembles in
       any way; see EXAMPLE below for how to build an oo::class that supports the API). 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 cmdPrefix 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 channels 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 cmdPrefix will receive
              for the specified channelId. It will be generated 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
              chan 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 channelId  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).
              However, 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.  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 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) 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.

              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.

              To  signal that the channel is not able to accept data for writing 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 chan seek and chan tell
              requests  on the channel channelId. If it is not supported then seeking will not be
              possible for the channel.

              The base argument is the same as the equivalent argument of the builtin chan  seek,
              namely:

              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  offset  is an integer number specifying the amount of bytes to seek forward or
              backward. A positive number should seek forward, 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) location 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  chan  seek,  or  chan  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 chan  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 configure) 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-specific  option  of
              channel channelId. If this subcommand is supported 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 or chan configure) 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  or chan configure) 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  or chan configure) 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 interface 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 function 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.

EXAMPLE

       This demonstrates how to make a channel that reads from a string.

              oo::class create stringchan {
                  variable data pos
                  constructor {string {encoding {}}} {
                      if {$encoding eq ""} {set encoding [encoding system]}
                      set data [encoding convertto $encoding $string]
                      set pos 0
                  }

                  method initialize {ch mode} {
                      return "initialize finalize watch read seek"
                  }
                  method finalize {ch} {
                      my destroy
                  }
                  method watch {ch events} {
                      # Must be present but we ignore it because we do not
                      # post any events
                  }

                  # Must be present on a readable channel
                  method read {ch count} {
                      set d [string range $data $pos [expr {$pos+$count-1}]]
                      incr pos [string length $d]
                      return $d
                  }

                  # This method is optional, but useful for the example below
                  method seek {ch offset base} {
                      switch $base {
                          start {
                              set pos $offset
                          }
                          current {
                              incr pos $offset
                          }
                          end {
                              set pos [string length $data]
                              incr pos $offset
                          }
                      }
                      if {$pos < 0} {
                          set pos 0
                      } elseif {$pos > [string length $data]} {
                          set pos [string length $data]
                      }
                      return $pos
                  }
              }

              # Now we create an instance...
              set string "The quick brown fox jumps over the lazy dog.\n"
              set ch [chan create read [stringchan new $string]]

              puts [gets $ch];   # Prints the whole string

              seek $ch -5 end;
              puts [read $ch];   # Prints just the last word

SEE ALSO

       chan(3tcl), transchan(3tcl)

KEYWORDS

       API, channel, ensemble, prefix, reflection