1refchan(n) Tcl Built-In Commands refchan(n)
2______________________________________________________________________________
6
8 refchan - command handler API of reflected channels
9
11 cmdPrefix option ?arg arg ...?
12______________________________________________________________________________
13
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 Of all the possible subcommands, the handler must support initialize,
25 finalize, and watch. Support for the other subcommands is optional.
26 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 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 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 Note: If the creation of the channel was aborted due to failures
46 here, then the finalize subcommand will not be called.
47 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 The subcommand must throw an error if the chosen mode is not
54 supported by the cmdPrefix.
55 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 The return value of this subcommand is ignored.
66 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 This subcommand is not invoked if the creation of the channel
73 was aborted during initialize (See above).
74 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 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 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 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 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 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 return -code error EAGAIN
110 or
111 error EAGAIN
112 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 For example, while on Linux both
120 return -code error -11
122 and
123 error -11
124 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 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 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 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 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 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 return -code error EAGAIN
159 or
160 error EAGAIN
161 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 For example, while on Linux both
169 return -code error -11
171 and
172 error -11
173 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 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 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 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 The base argument is the same as the equivalent argument of the
193 builtin chan seek, namely:
194 start Seeking is relative to the beginning of the channel.
196 current Seeking is relative to the current seek position.
198 end Seeking is relative to the end of the channel.
200 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 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 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 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 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 The return value of the subcommand is ignored.
230 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 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 The subcommand should return the value of the specified option.
243 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 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 The subcommand should return a list of all options and their
256 values. This list must have an even number of elements.
257 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 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 The return value of the subcommand is ignored.
271 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
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 The function Tcl_DriverGetHandleProc is not supported; i.e., reflected
282 channels do not have OS specific handles.
283 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 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
296 This demonstrates how to make a channel that reads from a string.
297 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 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 # 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 # 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 # 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 puts [gets $ch]; # Prints the whole string
352 seek $ch -5 end;
354 puts [read $ch]; # Prints just the last word
355
357 chan(n), transchan(n)
358
360 API, channel, ensemble, prefix, reflection
361Tcl 8.5 refchan(n)