home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _93b89631cf026b97c0d57bda97dbf730 < prev    next >
Text File  |  2000-03-23  |  6KB  |  142 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>POE::Filter - POE Protocol 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::Filter - POE Protocol 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 filter methods">PUBLIC FILTER METHODS</A></LI>
  26.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  27.     <LI><A HREF="#bugs">BUGS</A></LI>
  28.     <LI><A HREF="#authors & copyrights">AUTHORS & COPYRIGHTS</A></LI>
  29. </UL>
  30. <!-- INDEX END -->
  31.  
  32. <HR>
  33. <P>
  34. <H1><A NAME="name">NAME</A></H1>
  35. <P>POE::Filter - POE Protocol Abstraction</P>
  36. <P>
  37. <HR>
  38. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  39. <UL>
  40. <LI>Linux</LI>
  41. <LI>Solaris</LI>
  42. <LI>Windows</LI>
  43. </UL>
  44. <HR>
  45. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  46. <PRE>
  47.   $filter = new POE::Filter::Something();
  48.   $arrayref_of_logical_chunks =
  49.     $filter->get($arrayref_of_raw_chunks_from_driver);
  50.   $arrayref_of_streamable_chunks_for_driver =
  51.      $filter->put($arrayref_of_logical_chunks);</PRE>
  52. <P>
  53. <HR>
  54. <H1><A NAME="description">DESCRIPTION</A></H1>
  55. <P>Filters provide a generic interface for low and medium level
  56. protocols.  Wheels use this interface to communicate in different
  57. protocols without necessarily having to know the details for each.</P>
  58. <P>In theory, filters should be interchangeable.  In practice, stream and
  59. block protocols tend to be incompatible.</P>
  60. <P>
  61. <HR>
  62. <H1><A NAME="public filter methods">PUBLIC FILTER METHODS</A></H1>
  63. <P>These methods are the generic Filter interface.  Specific filters may
  64. have additional methods.</P>
  65. <UL>
  66. <LI>
  67. POE::Filter::new()
  68. <P>The <CODE>new()</CODE> method creates and initializes a new filter.  Specific
  69. filters may have different constructor parameters.</P>
  70. <P></P>
  71. <LI>
  72. POE::Filter::get($arrayref_of_raw_chunks_from_driver)
  73. <P>The <CODE>get()</CODE> method translates raw stream data into logical units.  It
  74. accepts a reference to an array of raw stream chunks as returned from
  75. POE::Driver::get().  It returns a reference to an array of complete
  76. logical data chunks.  There may or may not be a 1:1 correspondence
  77. between raw stream chunks and logical data chunks.</P>
  78. <P>Some filters may buffer partial logical units until they are completed
  79. in subsequent <CODE>get()</CODE> calls.</P>
  80. <P>The <CODE>get()</CODE> method returns a reference to an empty array if the stream
  81. doesn't include enough information for a complete logical unit.</P>
  82. <P></P>
  83. <LI>
  84. POE::Filter::put($arrayref_of_logical_chunks)
  85. <P>The <CODE>put()</CODE> method takes a reference to an array of logical data chunks.
  86. It serializes them into streamable representations suitable for
  87. POE::Driver::put().  It returns the raw streamable versions in a
  88. different array reference.</P>
  89. <P></P>
  90. <LI>
  91. POE::Filter::get_pending()
  92. <P>The <CODE>get_pending()</CODE> method is part of wheels' buffer swapping mechanism.
  93. It clears the filter's input buffer and returns a copy of whatever was
  94. in it.  It doesn't manipulate filters' output buffers because they
  95. don't exist (filters expect to receive entire logical data chunks from
  96. sessions, so there's no reason to buffer data and frame it).</P>
  97. <P><STRONG>Please note that relying on the get_pending() method in networked
  98. settings require some forethought.</STRONG> For instance, POE::Filter::Stream
  99. never buffers data.</P>
  100. <P>Switching filters usually requires some sort of flow control,
  101. otherwise it's easy to cause a race condition where one side sends the
  102. wrong type of information for the other side's current filter.
  103. Framing errors will ensue.  Consider the following:</P>
  104. <P>Assume a server and client are using POE::Filter::Line.  When the
  105. client asks the server to switch to POE::Filter::Reference, it should
  106. wait for the server's ACK or NAK before changing its own filter.  This
  107. lets the client avoid sending referenced data while the server still
  108. is parsing lines.</P>
  109. <P>Here's something else to consider.  Programs using POE::Wheel::put()
  110. on TCP sockets cannot rely on each put data chunk arriving separately
  111. on the receiving end of the connection.  This is because TCP coalesces
  112. packets whenever possible, to minimize packet header overhead.</P>
  113. <P>Most systems have a way to disable the TCP delay (Nagle's algorithm),
  114. in one form or another.  If you need this, please check your C headers
  115. for the TCP_NODELAY socket option.  It's neither portable, nor
  116. supported in Perl by default.</P>
  117. <P>The filterchange.perl sample program copes with flow control while
  118. switching filters.</P>
  119. <P></P></UL>
  120. <P>
  121. <HR>
  122. <H1><A NAME="see also">SEE ALSO</A></H1>
  123. <P>POE::Filter::HTTPD; POE::Filter::Line; POE::Filter::Reference;
  124. POE::Filter::Stream</P>
  125. <P>
  126. <HR>
  127. <H1><A NAME="bugs">BUGS</A></H1>
  128. <P>Oh, probably some.</P>
  129. <P>
  130. <HR>
  131. <H1><A NAME="authors & copyrights">AUTHORS & COPYRIGHTS</A></H1>
  132. <P>Please see the POE manpage.</P>
  133. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  134. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  135. <STRONG><P CLASS=block> POE::Filter - POE Protocol Abstraction</P></STRONG>
  136. </TD></TR>
  137. </TABLE>
  138.  
  139. </BODY>
  140.  
  141. </HTML>
  142.