Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

refchan (1t)

Name

refchan - command handler API of reflected channels

Synopsis

cmdPrefix option ?arg arg ...?

Description

refchan(1t)                  Tcl Built-In Commands                 refchan(1t)



______________________________________________________________________________

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  cre-
       ated  by  namespace  ensemble create, though the implementation of han-
       dlers 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 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 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  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.  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)  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 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  for-
              ward, and a negative number should seek backward.  A channel may
              provide only limited seeking. For example sockets can seek  for-
              ward, 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
              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 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 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 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  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 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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tcl-8    |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+

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.

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-
       core8.6.7-src.tar.gz.

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.

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(n), transchan(n)

KEYWORDS
       API, channel, ensemble, prefix, reflection




Tcl                                   8.5                          refchan(1t)