1[vset VERSION 1.0.1]
2[comment {-*- tcl -*- doctools manpage}]
3[manpage_begin tcl::chan::halfpipe n [vset VERSION]]
4[keywords callbacks]
5[keywords fifo]
6[keywords {in-memory channel}]
7[keywords {reflected channel}]
8[keywords {tip 219}]
9[keywords {virtual channel}]
10[copyright {2009, 2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
11[moddesc   {Reflected/virtual channel support}]
12[category  Channels]
13[titledesc {In-memory channel, half of a fifo2}]
14[require Tcl 8.5]
15[require TclOO]
16[require tcl::chan::events [opt 1]]
17[require tcl::chan::halfpipe [opt [vset VERSION]]]
18[description]
19[para]
20
21The [package tcl::chan::halfpipe] package provides a command creating
22one half of a [package tcl::chan::fifo2] pair. Writing into such a
23channel invokes a set of callbacks which then handle the data. This is
24similar to a channel handler, except having a much simpler API.
25
26[para] The internal [package TclOO] class implementing the channel
27handler is a sub-class of the [package tcl::chan::events] framework.
28
29[section API]
30
31[list_begin definitions]
32
33[call [cmd ::tcl::chan::halfpipe] [opt "[option -option] [arg value]..."]]
34
35This command creates a halfpipe channel and configures it with the
36callbacks to run when the channel is closed, data was written to it,
37or ran empty. See the section [sectref Options] for the list of
38options and associated semantics.
39
40The result of the command is a list containing two elements, the
41handle of the new channel, and the object command of the channel
42handler, in this order.
43
44The latter is supplied to the caller to provide her with access to the
45[method put] method for adding data to the channel.
46
47[para] Two halfpipes with a bit of glue logic in the callbacks make
48for one [package tcl::chan::fifo2].
49
50[call [arg objectCmd] [method put] [arg bytes]]
51
52This method of the channel handler object puts the data [arg bytes]
53into the channel so that it can be read from it.
54
55[list_end]
56
57[section Options]
58
59[list_begin options]
60[opt_def -close-command cmdprefix]
61
62This callback is invoked when the channel is closed.
63A single argument is supplied, the handle of the channel being closed.
64The result of the callback is ignored.
65
66[opt_def -write-command cmdprefix]
67
68This callback is invoked when data is written to the channel.
69Two arguments are supplied, the handle of the channel written to, and the data written.
70The result of the callback is ignored.
71
72[opt_def -empty-command cmdprefix]
73
74This callback is invoked when the channel has run out of data to read.
75A single argument is supplied, the handle of the channel.
76
77[list_end]
78
79[vset CATEGORY virtchannel]
80[include ../common-text/feedback.inc]
81[manpage_end]
82