1IO::Async::Channel(3) User Contributed Perl DocumentationIO::Async::Channel(3)
2
3
4

NAME

6       "IO::Async::Channel" - pass values into or out from an
7       IO::Async::Routine
8

DESCRIPTION

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
16       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
26       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

PARAMETERS

34       The following named parameters may be passed to "new" or "configure":
35
36   codec => STR
37       Gives the name of the encoding method used to represent values over the
38       channel.
39
40       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
44       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

CONSTRUCTOR

51   new
52          $channel = IO::Async::Channel->new
53
54       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()"
56       the two "setup_*" methods may be used to configure the object for
57       operation on either end.
58
59       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

METHODS

64       The following methods documented with a trailing call to "->get" return
65       Future instances.
66
67   configure
68          $channel->configure( %params )
69
70       Similar to the standard "configure" method on IO::Async::Notifier, this
71       is used to change details of the Channel's operation.
72
73       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
78            $on_recv->( $channel, $data )
79
80       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
84            $on_eof->( $channel )
85
86   send
87          $channel->send( $data )
88
89       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
92       the underlying filehandle blocks. When called on an asynchronous mode
93       channel this method will not block.
94
95   send_encoded
96          $channel->send_encoded( $record )
97
98       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
101   encode
102          $record = $channel->encode( $data )
103
104       Takes a Perl reference and returns a serialised string that can be
105       passed to "send_encoded". The following two forms are equivalent
106
107        $channel->send( $data )
108        $channel->send_encoded( $channel->encode( $data ) )
109
110       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
114          $record = IO::Async::Channel->encode( $data )
115
116       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
121   send_frozen
122          $channel->send_frozen( $record )
123
124       Legacy name for "send_encoded". This is no longer preferred as it
125       expects the data to be encoded using "Storable", which prevents (or at
126       least makes more awkward) the use of other codecs on a channel by
127       default. This method should not be used in new code and may be removed
128       in a later version.
129
130   recv
131          $data = $channel->recv
132
133       When called on a synchronous mode Channel this method will block until
134       a Perl reference value is available from the other end and then return
135       it. If the Channel is closed this method will return "undef". Since
136       only references may be passed and all Perl references are true the
137       truth of the result of this method can be used to detect that the
138       channel is still open and has not yet been closed.
139
140          $data = $channel->recv->get
141
142       When called on an asynchronous mode Channel this method returns a
143       future which will eventually yield the next Perl reference value that
144       becomes available from the other end. If the Channel is closed, the
145       future will fail with an "eof" failure.
146
147          $channel->recv( %args )
148
149       When not returning a future, takes the following named arguments:
150
151       on_recv => CODE
152               Called when a new Perl reference value is available. Will be
153               passed the Channel object and the reference data.
154
155                $on_recv->( $channel, $data )
156
157       on_eof => CODE
158               Called if the Channel was closed before a new value was ready.
159               Will be passed the Channel object.
160
161                $on_eof->( $channel )
162
163   close
164          $channel->close
165
166       Closes the channel. Causes a pending "recv" on the other end to return
167       undef or the queued "on_eof" callbacks to be invoked.
168

AUTHOR

170       Paul Evans <leonerd@leonerd.org.uk>
171
172
173
174perl v5.32.1                      2021-01-27             IO::Async::Channel(3)
Impressum