1refchan(n)                   Tcl Built-In Commands                  refchan(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       refchan - command handler API of reflected channels
9

SYNOPSIS

11       cmdPrefix option ?arg arg ...?
12______________________________________________________________________________
13

DESCRIPTION

15       The  Tcl-level handler for a reflected channel has to be a command with
16       subcommands (termed an ensemble, as it is a command such as  that  cre‐
17       ated  by  namespace  ensemble create, though the implementation of han‐
18       dlers for reflected channel is not tied to namespace ensembles  in  any
19       way;  see EXAMPLE below for how to build an oo::class that supports the
20       API). Note that cmdPrefix is whatever was specified in the call to chan
21       create, and may consist of multiple arguments; this will be expanded to
22       multiple words in place of the prefix.
23
24       Of all the possible subcommands, the handler must  support  initialize,
25       finalize, and watch. Support for the other subcommands is optional.
26
27   MANDATORY SUBCOMMANDS
28       cmdPrefix initialize channelId mode
29              An invocation of this subcommand will be the first call the cmd‐
30              Prefix will receive for the specified new channelId. It  is  the
31              responsibility  of  this  subcommand to set up any internal data
32              structures required to keep track of the channel and its state.
33
34              The return value of the method has to be a list  containing  the
35              names  of  all subcommands supported by the cmdPrefix. This also
36              tells the Tcl core which version of the API for reflected  chan‐
37              nels is used by this command handler.
38
39              Any  error  thrown  by the method will abort the creation of the
40              channel and no channel will be created. The  thrown  error  will
41              appear  as error thrown by chan create. Any exception other than
42              an error (e.g., break, etc.) is treated as (and converted to) an
43              error.
44
45              Note: If the creation of the channel was aborted due to failures
46              here, then the finalize subcommand will not be called.
47
48              The mode argument tells the  handler  whether  the  channel  was
49              opened  for  reading,  writing, or both. It is a list containing
50              any of the strings read or write. The list will  always  contain
51              at least one element.
52
53              The  subcommand  must  throw  an error if the chosen mode is not
54              supported by the cmdPrefix.
55
56       cmdPrefix finalize channelId
57              An invocation of this subcommand will be the last call the  cmd‐
58              Prefix will receive for the specified channelId. It will be gen‐
59              erated just before the destruction of the data structures of the
60              channel  held  by  the  Tcl  core.  The command handler must not
61              access the channelId anymore in no  way.  Upon  this  subcommand
62              being  called,  any internal resources allocated to this channel
63              must be cleaned up.
64
65              The return value of this subcommand is ignored.
66
67              If the subcommand throws an error the command which  caused  its
68              invocation  (usually chan close) will appear to have thrown this
69              error. Any exception beyond error (e.g., break, etc.) is treated
70              as (and converted to) an error.
71
72              This  subcommand  is  not invoked if the creation of the channel
73              was aborted during initialize (See above).
74
75       cmdPrefix watch channelId eventspec
76              This subcommand notifies the cmdPrefix that the specified  chan‐
77              nelId  is interested in the events listed in the eventspec. This
78              argument is a list containing any of read and  write.  The  list
79              may be empty, which signals that the channel does not wish to be
80              notified of any events. In that situation,  the  handler  should
81              disable event generation completely.
82
83              Warning:  Any  return  value  of the subcommand is ignored. This
84              includes all errors thrown by the subcommand,  break,  continue,
85              and custom return codes.
86
87              This subcommand interacts with chan postevent. Trying to post an
88              event which was not listed in the last call to watch will  cause
89              chan postevent to throw an error.
90
91   OPTIONAL SUBCOMMANDS
92       cmdPrefix read channelId count
93              This  optional  subcommand is called when the user requests data
94              from the channel channelId. count specifies how many bytes  have
95              been  requested.  If  the subcommand is not supported then it is
96              not possible to read from the channel handled by the command.
97
98              The return value of this subcommand is taken  as  the  requested
99              data  bytes.  If  the  returned  data  contains  more bytes than
100              requested, an error will be signaled and  later  thrown  by  the
101              command  which  performed  the read (usually gets or read). How‐
102              ever, returning fewer bytes than requested is acceptable.
103
104              Note that returning nothing (0 bytes) is a signal to the  higher
105              layers  that EOF has been reached on the channel. To signal that
106              the channel is out of data right now, but has  not  yet  reached
107              EOF, it is necessary to throw the error "EAGAIN", i.e. to either
108
109                     return -code error EAGAIN
110              or
111                     error EAGAIN
112
113              For  extensibility  any  error whose value is a negative integer
114              number will cause the higher layers to set the C-level  variable
115              "errno" to the absolute value of this number, signaling a system
116              error.  However, note that the exact mapping between these error
117              numbers and their meanings is operating system dependent.
118
119              For example, while on Linux both
120
121                     return -code error -11
122              and
123                     error -11
124
125              are  equivalent  to  the examples above, using the more readable
126              string "EAGAIN", this is not true for BSD, where the  equivalent
127              number is -35.
128
129              The  symbolic  string  however  is  the same across systems, and
130              internally translated to the  correct  number.  No  other  error
131              value has such a mapping to a symbolic string.
132
133              If  the  subcommand  throws  any  other error, the command which
134              caused its invocation (usually gets, or  read)  will  appear  to
135              have   thrown   this   error.   Any   exception   beyond  error,
136              (e.g., break, etc.) is treated as and converted to an error.
137
138       cmdPrefix write channelId data
139              This optional subcommand is called when the user writes data  to
140              the  channel  channelId.  The  data argument contains bytes, not
141              characters. Any type of transformation (EOL,  encoding)  config‐
142              ured  for the channel has already been applied at this point. If
143              this subcommand is not supported then  it  is  not  possible  to
144              write to the channel handled by the command.
145
146              The  return  value  of  the subcommand is taken as the number of
147              bytes written by the channel. Anything non-numeric will cause an
148              error  to be signaled and later thrown by the command which per‐
149              formed the write.  A  negative  value  implies  that  the  write
150              failed. Returning a value greater than the number of bytes given
151              to the handler, or zero, is forbidden and  will  cause  the  Tcl
152              core to throw an error.
153
154              To  signal that the channel is not able to accept data for writ‐
155              ing right now, it is necessary to throw the error "EAGAIN", i.e.
156              to either
157
158                     return -code error EAGAIN
159              or
160                     error EAGAIN
161
162              For  extensibility  any  error whose value is a negative integer
163              number will cause the higher layers to set the C-level  variable
164              "errno" to the absolute value of this number, signaling a system
165              error.  However, note that the exact mapping between these error
166              numbers and their meanings is operating system dependent.
167
168              For example, while on Linux both
169
170                     return -code error -11
171              and
172                     error -11
173
174              are  equivalent  to  the examples above, using the more readable
175              string "EAGAIN", this is not true for BSD, where the  equivalent
176              number is -35.
177
178              The  symbolic  string  however  is  the same across systems, and
179              internally translated to the  correct  number.  No  other  error
180              value has such a mapping to a symbolic string.
181
182              If  the  subcommand  throws  any  other  error the command which
183              caused its invocation (usually puts) will appear to have  thrown
184              this  error.   Any exception beyond error (e.g., break, etc.) is
185              treated as and converted to an error.
186
187       cmdPrefix seek channelId offset base
188              This optional subcommand is responsible for the handling of chan
189              seek  and  chan tell requests on the channel channelId. If it is
190              not supported then seeking will not be possible for the channel.
191
192              The base argument is the same as the equivalent argument of  the
193              builtin chan seek, namely:
194
195              start     Seeking is relative to the beginning of the channel.
196
197              current   Seeking is relative to the current seek position.
198
199              end       Seeking is relative to the end of the channel.
200
201              The  offset  is an integer number specifying the amount of bytes
202              to seek forward or backward. A positive number should seek  for‐
203              ward, and a negative number should seek backward.  A channel may
204              provide only limited seeking. For example sockets can seek  for‐
205              ward, but not backward.
206
207              The  return  value of the subcommand is taken as the (new) loca‐
208              tion of the channel, counted from the start. This has to  be  an
209              integer number greater than or equal to zero.  If the subcommand
210              throws an error the command which caused its invocation (usually
211              chan  seek, or chan tell) will appear to have thrown this error.
212              Any exception beyond error (e.g., break, etc.) is treated as and
213              converted to an error.
214
215              The  offset/base  combination  of  0/current signals a chan tell
216              request, i.e., seek nothing relative to  the  current  location,
217              making  the  new location identical to the current one, which is
218              then returned.
219
220       cmdPrefix configure channelId option value
221              This  optional  subcommand  is  for  setting  the  type-specific
222              options  of channel channelId. The option argument indicates the
223              option to be written, and the value argument indicates the value
224              to set the option to.
225
226              This subcommand will never try to update more than one option at
227              a time; that is behavior implemented in the Tcl channel core.
228
229              The return value of the subcommand is ignored.
230
231              If the subcommand throws an error the  command  which  performed
232              the  (re)configuration or query (usually fconfigure or chan con‐
233              figure) will appear to have thrown  this  error.  Any  exception
234              beyond  error (e.g., break, etc.) is treated as and converted to
235              an error.
236
237       cmdPrefix cget channelId option
238              This optional subcommand is used when reading a single type-spe‐
239              cific  option  of  channel channelId. If this subcommand is sup‐
240              ported then the subcommand cgetall must be supported as well.
241
242              The subcommand should return the value of the specified option.
243
244              If the subcommand throws an error, the command  which  performed
245              the  (re)configuration or query (usually fconfigure or chan con‐
246              figure) will appear to have thrown  this  error.  Any  exception
247              beyond  error (e.g., break, etc.) is treated as and converted to
248              an error.
249
250       cmdPrefix cgetall channelId
251              This optional subcommand is used for reading  all  type-specific
252              options  of  channel  channelId. If this subcommand is supported
253              then the subcommand cget has to be supported as well.
254
255              The subcommand should return a list of  all  options  and  their
256              values.  This list must have an even number of elements.
257
258              If  the  subcommand  throws an error the command which performed
259              the (re)configuration or query (usually fconfigure or chan  con‐
260              figure)  will  appear  to  have thrown this error. Any exception
261              beyond error (e.g., break, etc.) is treated as and converted  to
262              an error.
263
264       cmdPrefix blocking channelId mode
265              This optional subcommand handles changes to the blocking mode of
266              the channel channelId. The mode is a boolean flag. A true  value
267              means  that  the  channel has to be set to blocking, and a false
268              value means that the channel should be non-blocking.
269
270              The return value of the subcommand is ignored.
271
272              If the subcommand throws an error the command which  caused  its
273              invocation (usually fconfigure or chan configure) will appear to
274              have thrown this error. Any exception beyond error (e.g., break,
275              etc.) is treated as and converted to an error.
276

NOTES

278       Some  of  the functions supported in channels defined in Tcl's C inter‐
279       face are not available to channels reflected to the Tcl level.
280
281       The function Tcl_DriverGetHandleProc is not supported;  i.e., reflected
282       channels do not have OS specific handles.
283
284       The  function Tcl_DriverHandlerProc is not supported. This driver func‐
285       tion is relevant  only  for  stacked  channels,  i.e., transformations.
286       Reflected channels are always base channels, not transformations.
287
288       The  function Tcl_DriverFlushProc is not supported. This is because the
289       current generic I/O layer of Tcl does not use this function anywhere at
290       all. Therefore support at the Tcl level makes no sense either. This may
291       be altered in the future (through extending the API  defined  here  and
292       changing  its  version number) should the function be used at some time
293       in the future.
294

EXAMPLE

296       This demonstrates how to make a channel that reads from a string.
297
298              oo::class create stringchan {
299                  variable data pos
300                  constructor {string {encoding {}}} {
301                      if {$encoding eq ""} {set encoding [encoding system]}
302                      set data [encoding convertto $encoding $string]
303                      set pos 0
304                  }
305
306                  method initialize {ch mode} {
307                      return "initialize finalize watch read seek"
308                  }
309                  method finalize {ch} {
310                      my destroy
311                  }
312                  method watch {ch events} {
313                      # Must be present but we ignore it because we do not
314                      # post any events
315                  }
316
317                  # Must be present on a readable channel
318                  method read {ch count} {
319                      set d [string range $data $pos [expr {$pos+$count-1}]]
320                      incr pos [string length $d]
321                      return $d
322                  }
323
324                  # This method is optional, but useful for the example below
325                  method seek {ch offset base} {
326                      switch $base {
327                          start {
328                              set pos $offset
329                          }
330                          current {
331                              incr pos $offset
332                          }
333                          end {
334                              set pos [string length $data]
335                              incr pos $offset
336                          }
337                      }
338                      if {$pos < 0} {
339                          set pos 0
340                      } elseif {$pos > [string length $data]} {
341                          set pos [string length $data]
342                      }
343                      return $pos
344                  }
345              }
346
347              # Now we create an instance...
348              set string "The quick brown fox jumps over the lazy dog.\n"
349              set ch [chan create read [stringchan new $string]]
350
351              puts [gets $ch];   # Prints the whole string
352
353              seek $ch -5 end;
354              puts [read $ch];   # Prints just the last word
355

SEE ALSO

357       chan(n), transchan(n)
358

KEYWORDS

360       API, channel, ensemble, prefix, reflection
361
362
363
364Tcl                                   8.5                           refchan(n)
Impressum