Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
refchan(n)		     Tcl Built-In Commands		    refchan(n)

______________________________________________________________________________

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 ac-
	      cess 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 in-
	      cludes 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 re-
	      quested, an error	will be	signaled and later thrown by the  com-
	      mand  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 in-
	      ternally 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 in-
	      ternally 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 re-
	      quest, i.e., seek	nothing	relative to the	current	location, mak-
	      ing 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  op-
	      tions  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 be-
	      yond 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 be-
	      yond 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 be-
	      yond 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	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.  Re-
       flected 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(n),	transchan(n)

KEYWORDS
       API, channel, ensemble, prefix, reflection

Tcl				      8.5			    refchan(n)

NAME | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLE | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=refchan.tcl87&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help