1IO::Async::Channel(3pm)User Contributed Perl DocumentatioInO::Async::Channel(3pm)
2
6 "IO::Async::Channel" - pass values into or out from an
7 IO::Async::Routine
8
10 A "IO::Async::Channel" object allows Perl values to be passed into or
11 out of an IO::Async::Routine. It is intended to be used primarily with
12 a Routine object rather than independently. For more detail and
13 examples on how to use this object see also the documentation for
14 IO::Async::Routine.
15 A Channel object is shared between the main process of the program and
17 the process running within the Routine. In the main process it will be
18 used in asynchronous mode, and in the Routine process it will be used
19 in synchronous mode. In asynchronous mode all methods return
20 immediately and use IO::Async-style futures or callback functions. In
21 synchronous within the Routine process the methods block until they are
22 ready and may be used for flow-control within the routine.
23 Alternatively, a Channel may be shared between two different Routine
24 objects, and not used directly by the controlling program.
25 The channel itself represents a FIFO of Perl reference values. New
27 values may be put into the channel by the "send" method in either mode.
28 Values may be retrieved from it by the "recv" method. Values inserted
29 into the Channel are snapshot by the "send" method. Any changes to
30 referred variables will not be observed by the other end of the Channel
31 after the "send" method returns.
32
34 The following named parameters may be passed to "new" or "configure":
35 codec => STR
37 Gives the name of the encoding method used to represent values over the
38 channel.
39 This can be set to "Storable" to use the core Storable module. As this
41 only supports references, to pass a single scalar value, "send" a
42 SCALAR reference to it, and dereference the result of "recv".
43 If the Sereal::Encoder and Sereal::Decoder modules are installed, this
45 can be set to "Sereal" instead, and will use those to perform the
46 encoding and decoding. This optional dependency may give higher
47 performance than using "Storable". If these modules are available, then
48 this option is picked by default.
49
51 new
52 $channel = IO::Async::Channel->new
53 Returns a new "IO::Async::Channel" object. This object reference itself
55 should be shared by both sides of a fork()ed process. After fork() the
56 two "setup_*" methods may be used to configure the object for operation
57 on either end.
58 While this object does in fact inherit from IO::Async::Notifier, it
60 should not be added to a Loop object directly; event management will be
61 handled by its containing IO::Async::Routine object.
62
64 The following methods documented with a trailing call to "->get" return
65 Future instances.
66 configure
68 $channel->configure( %params )
69 Similar to the standard "configure" method on IO::Async::Notifier, this
71 is used to change details of the Channel's operation.
72 on_recv => CODE
74 May only be set on an async mode channel. If present, will be
75 invoked whenever a new value is received, rather than using the
76 "recv" method.
77 $on_recv->( $channel, $data )
79 on_eof => CODE
81 May only be set on an async mode channel. If present, will be
82 invoked when the channel gets closed by the peer.
83 $on_eof->( $channel )
85 send
87 $channel->send( $data )
88 Pushes the data stored in the given Perl reference into the FIFO of the
90 Channel, where it can be received by the other end. When called on a
91 synchronous mode Channel this method may block if a write() call on the
92 underlying filehandle blocks. When called on an asynchronous mode
93 channel this method will not block.
94 send_encoded
96 $channel->send_encoded( $record )
97 A variant of the "send" method; this method pushes the byte record
99 given. This should be the result of a call to "encode".
100 encode
102 $record = $channel->encode( $data )
103 Takes a Perl reference and returns a serialised string that can be
105 passed to "send_encoded". The following two forms are equivalent
106 $channel->send( $data )
108 $channel->send_encoded( $channel->encode( $data ) )
109 This is provided for the use-case where data needs to be serialised
111 into a fixed string to "snapshot it" but not sent yet; the returned
112 string can be saved and sent at a later time.
113 $record = IO::Async::Channel->encode( $data )
115 This can also be used as a class method, in case it is inconvenient to
117 operate on a particular object instance, or when one does not exist
118 yet. In this case it will encode using whatever is the default codec
119 for "IO::Async::Channel".
120 recv
122 $data = $channel->recv
123 When called on a synchronous mode Channel this method will block until
125 a Perl reference value is available from the other end and then return
126 it. If the Channel is closed this method will return "undef". Since
127 only references may be passed and all Perl references are true the
128 truth of the result of this method can be used to detect that the
129 channel is still open and has not yet been closed.
130 $data = $channel->recv->get
132 When called on an asynchronous mode Channel this method returns a
134 future which will eventually yield the next Perl reference value that
135 becomes available from the other end. If the Channel is closed, the
136 future will fail with an "eof" failure.
137 $channel->recv( %args )
139 When not returning a future, takes the following named arguments:
141 on_recv => CODE
143 Called when a new Perl reference value is available. Will be
144 passed the Channel object and the reference data.
145 $on_recv->( $channel, $data )
147 on_eof => CODE
149 Called if the Channel was closed before a new value was ready.
150 Will be passed the Channel object.
151 $on_eof->( $channel )
153 close
155 $channel->close
156 Closes the channel. Causes a pending "recv" on the other end to return
158 undef or the queued "on_eof" callbacks to be invoked.
159
161 Paul Evans <leonerd@leonerd.org.uk>
162perl v5.36.1 2023-05-14 IO::Async::Channel(3pm)