.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "IO::Async::Channel 3pm" .TH IO::Async::Channel 3pm "2014-10-21" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "IO::Async::Channel" \- pass values into or out from an IO::Async::Routine .SH "DESCRIPTION" .IX Header "DESCRIPTION" A \f(CW\*(C`IO::Async::Channel\*(C'\fR object allows Perl values to be passed into or out of an IO::Async::Routine. It is intended to be used primarily with a Routine object rather than independently. For more detail and examples on how to use this object see also the documentation for IO::Async::Routine. .PP A Channel object is shared between the main process of the program and the process running within the Routine. In the main process it will be used in asynchronous mode, and in the Routine process it will be used in synchronous mode. In asynchronous mode all methods return immediately and use \&\f(CW\*(C`IO::Async\*(C'\fR\-style futures or callback functions. In synchronous within the Routine process the methods block until they are ready and may be used for flow-control within the routine. Alternatively, a Channel may be shared between two different Routine objects, and not used directly by the controlling program. .PP The channel itself represents a \s-1FIFO\s0 of Perl reference values. New values may be put into the channel by the \f(CW\*(C`send\*(C'\fR method in either mode. Values may be retrieved from it by the \f(CW\*(C`recv\*(C'\fR method. Values inserted into the Channel are snapshot by the \f(CW\*(C`send\*(C'\fR method. Any changes to referred variables will not be observed by the other end of the Channel after the \f(CW\*(C`send\*(C'\fR method returns. .PP Since the channel uses Storable to serialise values to write over the communication filehandle only reference values may be passed. To pass a single scalar value, \f(CW\*(C`send\*(C'\fR a \s-1SCALAR\s0 reference to it, and dereference the result of \&\f(CW\*(C`recv\*(C'\fR. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .ie n .SS "$channel = IO::Async::Channel\->new" .el .SS "\f(CW$channel\fP = IO::Async::Channel\->new" .IX Subsection "$channel = IO::Async::Channel->new" Returns a new \f(CW\*(C`IO::Async::Channel\*(C'\fR object. This object reference itself should be shared by both sides of a \f(CW\*(C`fork()\*(C'\fRed process. After \f(CW\*(C`fork()\*(C'\fR the two \f(CW\*(C`setup_*\*(C'\fR methods may be used to configure the object for operation on either end. .PP While this object does in fact inherit from IO::Async::Notifier for implementation reasons it is not intended that this object be used as a Notifier. It should not be added to a Loop object directly; event management will be handled by its containing \f(CW\*(C`IO::Async::Routine\*(C'\fR object. .SH "METHODS" .IX Header "METHODS" The following methods documented with a trailing call to \f(CW\*(C`\->get\*(C'\fR return Future instances. .ie n .SS "$channel\->configure( %params )" .el .SS "\f(CW$channel\fP\->configure( \f(CW%params\fP )" .IX Subsection "$channel->configure( %params )" Similar to the standard \f(CW\*(C`configure\*(C'\fR method on \f(CW\*(C`IO::Async::Notifier\*(C'\fR, this is used to change details of the Channel's operation. .IP "on_recv => \s-1CODE\s0" 4 .IX Item "on_recv => CODE" May only be set on an async mode channel. If present, will be invoked whenever a new value is received, rather than using the \f(CW\*(C`recv\*(C'\fR method. .Sp .Vb 1 \& $on_recv\->( $channel, $data ) .Ve .IP "on_eof => \s-1CODE\s0" 4 .IX Item "on_eof => CODE" May only be set on an async mode channel. If present, will be invoked when the channel gets closed by the peer. .Sp .Vb 1 \& $on_eof\->( $channel ) .Ve .ie n .SS "$channel\->send( $data )" .el .SS "\f(CW$channel\fP\->send( \f(CW$data\fP )" .IX Subsection "$channel->send( $data )" Pushes the data stored in the given Perl reference into the \s-1FIFO\s0 of the Channel, where it can be received by the other end. When called on a synchronous mode Channel this method may block if a \f(CW\*(C`write()\*(C'\fR call on the underlying filehandle blocks. When called on an asynchronous mode channel this method will not block. .ie n .SS "$channel\->send_frozen( $record )" .el .SS "\f(CW$channel\fP\->send_frozen( \f(CW$record\fP )" .IX Subsection "$channel->send_frozen( $record )" A variant of the \f(CW\*(C`send\*(C'\fR method; this method pushes the byte record given. This should be the result of a call to \f(CW\*(C`Storable::freeze()\*(C'\fR. .ie n .SS "$data = $channel\->recv" .el .SS "\f(CW$data\fP = \f(CW$channel\fP\->recv" .IX Subsection "$data = $channel->recv" When called on a synchronous mode Channel this method will block until a Perl reference value is available from the other end and then return it. If the Channel is closed this method will return \f(CW\*(C`undef\*(C'\fR. Since only references may be passed and all Perl references are true the truth of the result of this method can be used to detect that the channel is still open and has not yet been closed. .ie n .SS "$data = $channel\->recv\->get" .el .SS "\f(CW$data\fP = \f(CW$channel\fP\->recv\->get" .IX Subsection "$data = $channel->recv->get" When called on an asynchronous mode Channel this method returns a future which will eventually yield the next Perl reference value that becomes available from the other end. If the Channel is closed, the future will fail with an \&\f(CW\*(C`eof\*(C'\fR failure. .ie n .SS "$channel\->recv( %args )" .el .SS "\f(CW$channel\fP\->recv( \f(CW%args\fP )" .IX Subsection "$channel->recv( %args )" When not returning a future, takes the following named arguments: .IP "on_recv => \s-1CODE\s0" 8 .IX Item "on_recv => CODE" Called when a new Perl reference value is available. Will be passed the Channel object and the reference data. .Sp .Vb 1 \& $on_recv\->( $channel, $data ) .Ve .IP "on_eof => \s-1CODE\s0" 8 .IX Item "on_eof => CODE" Called if the Channel was closed before a new value was ready. Will be passed the Channel object. .Sp .Vb 1 \& $on_eof\->( $channel ) .Ve .ie n .SS "$channel\->close" .el .SS "\f(CW$channel\fP\->close" .IX Subsection "$channel->close" Closes the channel. Causes a pending \f(CW\*(C`recv\*(C'\fR on the other end to return undef or the queued \f(CW\*(C`on_eof\*(C'\fR callbacks to be invoked. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans