home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _c7aa4e056464fe8d4cbe7bfa0dc149c0 < prev    next >
Text File  |  2000-03-23  |  6KB  |  175 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#public methods">PUBLIC METHODS</A></LI>
  26.     <LI><A HREF="#events and parameters">EVENTS AND PARAMETERS</A></LI>
  27.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  28.     <LI><A HREF="#bugs">BUGS</A></LI>
  29.     <LI><A HREF="#authors & copyrights">AUTHORS & COPYRIGHTS</A></LI>
  30. </UL>
  31. <!-- INDEX END -->
  32.  
  33. <HR>
  34. <P>
  35. <H1><A NAME="name">NAME</A></H1>
  36. <P>POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction</P>
  37. <P>
  38. <HR>
  39. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  40. <UL>
  41. <LI>Linux</LI>
  42. <LI>Solaris</LI>
  43. <LI>Windows</LI>
  44. </UL>
  45. <HR>
  46. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  47. <PRE>
  48.   $wheel = new POE::Wheel::ReadWrite(</PRE>
  49. <PRE>
  50.     # To read and write from the same handle, such as a socket, use
  51.     # the Handle parameter:
  52.     Handle       => $file_or_socket_handle,       # Handle to read/write</PRE>
  53. <PRE>
  54.     # To read and write from different handles, such as a dual pipe to
  55.     # a child process, or a console, use InputHandle and OutputHandle:
  56.     InputHandle  => $readable_filehandle,         # Handle to read
  57.     OutputHandle => $writable_filehandle,         # Handle to write</PRE>
  58. <PRE>
  59.     Driver       => new POE::Driver::Something(), # How to read/write it
  60.     Filter       => new POE::Filter::Something(), # How to parse it
  61.     InputState   => $input_state_name,  # Input received state
  62.     FlushedState => $flush_state_name,  # Output flushed state
  63.     ErrorState   => $error_state_name,  # Error occurred state
  64.   );</PRE>
  65. <PRE>
  66.   $wheel->put( $something );
  67.   $wheel->event( ... );
  68.   $wheel->set_filter( new POE::Filter::Something );</PRE>
  69. <P>
  70. <HR>
  71. <H1><A NAME="description">DESCRIPTION</A></H1>
  72. <P>The ReadWrite wheel does buffered, select-based I/O on a filehandle.
  73. It generates events for common file conditions, such as when data has
  74. been read or flushed.  This wheel includes a <CODE>put()</CODE> method.</P>
  75. <P>
  76. <HR>
  77. <H1><A NAME="public methods">PUBLIC METHODS</A></H1>
  78. <UL>
  79. <LI>
  80. POE::Wheel::ReadWrite::put($logical_data_chunk)
  81. <P>The <CODE>put()</CODE> method uses a POE::Filter to translate the logical data
  82. chunk into a serialized (streamable) representation.  It then uses a
  83. POE::Driver to enqueue or write the data to a filehandle.  It also
  84. manages the wheel's write select so that any buffered data can be
  85. flushed when the handle is ready.</P>
  86. <P></P>
  87. <LI>
  88. POE::Wheel::ReadWrite::event(...)
  89. <P>Please see POE::Wheel.</P>
  90. <P></P>
  91. <LI>
  92. POE::Wheel::ReadWrite::set_filter( $poe_filter )
  93. <P>The set_filter method changes the filter that the ReadWrite wheel uses
  94. to translate between streams and logical chunks of data.  It uses
  95. filters' <CODE>get_pending()</CODE> method to preserve any buffered data between
  96. the previous and new filters.</P>
  97. <P>Please be aware that this method has complex and perhaps non-obvious
  98. side effects.  The description of POE::Filter::get_pending() discusses
  99. them further.</P>
  100. <P>POE::Filter::HTTPD does not support the <CODE>get_pending()</CODE> method.
  101. Switching from an HTTPD filter to another one will display a reminder
  102. that it sn't supported.</P>
  103. <P></P></UL>
  104. <P>
  105. <HR>
  106. <H1><A NAME="events and parameters">EVENTS AND PARAMETERS</A></H1>
  107. <UL>
  108. <LI>
  109. InputState
  110. <P>The InputState event contains the name of the state that will be
  111. called for each chunk of logical data returned by the ReadWrite
  112. wheel's filter.</P>
  113. <P>The ARG0 parameter contains the chunk of logical data that was
  114. received.</P>
  115. <P>A sample InputState state:</P>
  116. <PRE>
  117.   sub input_state {
  118.     my ($heap, $input) = @_[HEAP, ARG0];
  119.     print "Echoing input: $input\n";
  120.     $heap->{wheel}->put($input);     # Echo it back.
  121.   }</PRE>
  122. <P></P>
  123. <LI>
  124. FlushedState
  125. <P>The FlushedState event contains the name of the state that will be
  126. called whenever the wheel's driver's output queue becomes empty.  This
  127. signals that all pending data has been written.  It does not include
  128. parameters.</P>
  129. <P>A sample FlushedState state:</P>
  130. <PRE>
  131.   sub flushed_state {
  132.     # Stop the wheel after all outgoing data is flushed.
  133.     # This frees the wheel's resources, including the
  134.     # filehandle, and closes the connection.
  135.     delete $_[HEAP]->{wheel};
  136.   }</PRE>
  137. <P></P>
  138. <LI>
  139. ErrorState
  140. <P>The ErrorState event contains the name of the state that will be
  141. called when a file error occurs.  The ReadWrite wheel knows what to do
  142. with EAGAIN, so it's not considered a true error.</P>
  143. <P>The ARG0 parameter contains the name of the function that failed.
  144. ARG1 and ARG2 contain the numeric and string versions of $! at the
  145. time of the error, respectively.</P>
  146. <P>A sample ErrorState state:</P>
  147. <PRE>
  148.   sub error_state {
  149.     my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
  150.     warn "$operation error $errnum: $errstr\n";
  151.   }</PRE>
  152. <P></P></UL>
  153. <P>
  154. <HR>
  155. <H1><A NAME="see also">SEE ALSO</A></H1>
  156. <P>POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept;
  157. POE::Wheel::SocketFactory</P>
  158. <P>
  159. <HR>
  160. <H1><A NAME="bugs">BUGS</A></H1>
  161. <P>Oh, probably some.</P>
  162. <P>
  163. <HR>
  164. <H1><A NAME="authors & copyrights">AUTHORS & COPYRIGHTS</A></H1>
  165. <P>Please see the POE manpage.</P>
  166. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  167. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  168. <STRONG><P CLASS=block> POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction</P></STRONG>
  169. </TD></TR>
  170. </TABLE>
  171.  
  172. </BODY>
  173.  
  174. </HTML>
  175.