home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / Wheel.pm < prev    next >
Encoding:
Perl POD Document  |  2003-11-21  |  4.0 KB  |  157 lines
  1. # $Id: Wheel.pm,v 1.18 2003/11/21 05:08:25 rcaputo Exp $
  2.  
  3. package POE::Wheel;
  4.  
  5. use strict;
  6.  
  7. use vars qw($VERSION);
  8. $VERSION = do {my@r=(q$Revision: 1.18 $=~/\d+/g);sprintf"%d."."%04d"x$#r,@r};
  9.  
  10. use Carp qw(croak);
  11.  
  12. # Used to generate unique IDs for wheels.  This is static data, shared
  13. # by all.
  14. my $next_id = 1;
  15. my %active_wheel_ids;
  16.  
  17. sub new {
  18.   my $type = shift;
  19.   croak "$type is not meant to be used directly";
  20. }
  21.  
  22. sub allocate_wheel_id {
  23.   while (1) {
  24.     last unless exists $active_wheel_ids{ ++$next_id };
  25.   }
  26.   return $active_wheel_ids{$next_id} = $next_id;
  27. }
  28.  
  29. sub free_wheel_id {
  30.   my $id = shift;
  31.   delete $active_wheel_ids{$id};
  32. }
  33.  
  34. #------------------------------------------------------------------------------
  35. 1;
  36.  
  37. __END__
  38.  
  39. =head1 NAME
  40.  
  41. POE::Wheel - high-level protocol logic
  42.  
  43. =head1 SYNOPSIS
  44.  
  45.   $wheel = POE::Wheel::Something->new( ... );
  46.   $wheel->put($some_logical_data_chunks);
  47.  
  48. =head1 DESCRIPTION
  49.  
  50. Wheels are bundles of event handlers (states) which perform common
  51. tasks.  Wheel::FollowTail, for example, contains I/O handlers for
  52. watching a file as it grows and reading the new information when it
  53. appears.
  54.  
  55. Unlike Components, Wheels do not stand alone.  Each wheel must be
  56. created by a session, and each belongs to their parent session until
  57. it's destroyed.
  58.  
  59. =head1 COMMON PUBLIC WHEEL METHODS
  60.  
  61. These methods are the generic Wheel interface, and every filter must
  62. implement them.
  63.  
  64. =over 2
  65.  
  66. =item new LOTS_OF_STUFF
  67.  
  68. new() creates a new wheel, returning the wheels reference.  The new
  69. wheel will continue to run for as long as it exists.  Every wheel has
  70. a different purpose and requires different parameters, so
  71. LOTS_OF_STUFF will vary from one to the next.
  72.  
  73. =item DESTROY
  74.  
  75. Perl calls DESTROY when the wheel's last reference is relinquished.
  76. This triggers the wheel's destruction, which stops the wheel and
  77. releases whatever resources it was managing.
  78.  
  79. =item event TYPE => EVENT_NAME, ...
  80.  
  81. event() changes the events that a wheel will emit.  Its parameters are
  82. pairs of event TYPEs and the EVENT_NAMEs to emit when each type of
  83. event occurs.
  84.  
  85. Event TYPEs differ for each wheel, and their manpages discuss them in
  86. greater detail.  EVENT_NAMEs may be undef, in which case a wheel will
  87. stop emitting an event for that TYPE.
  88.  
  89. This example changes the events to emit on new input and when output
  90. is flushed.  It stops the wheel from emitting events when errors
  91. occur.
  92.  
  93.   $wheel->event( InputEvent   => 'new_input_event',
  94.                  ErrorEvent   => undef,
  95.                  FlushedEvent => 'new_flushed_event',
  96.                );
  97.  
  98. =back
  99.  
  100. =head1 I/O WHEEL COMMON METHODS
  101.  
  102. These methods are common to I/O wheels.  Some I/O wheels are read-only
  103. and will not have a put() method.
  104.  
  105. =over 2
  106.  
  107. =item put LIST
  108.  
  109. put() sends a LIST of one or more records to the wheel for
  110. transmitting.  Each thing in the LIST is serialized by the wheel's
  111. Filter, and then buffered in the wheel's Driver until it can be
  112. flushed to its filehandle.
  113.  
  114. =back
  115.  
  116. =head1 STATIC FUNCTIONS
  117.  
  118. These functions keep global information about all wheels.  They should
  119. be called as normal functions:
  120.  
  121.   &POE::Wheel::function( ... );
  122.  
  123. =over 2
  124.  
  125. =item allocate_wheel_id
  126.  
  127. allocate_wheel_id() allocates a unique identifier for a wheel.  Wheels
  128. pass these identifiers back to sessions in their events so that
  129. sessions with several wheels can match events back to other
  130. information.
  131.  
  132. POE::Wheel keeps track of allocated IDs to avoid collisions.  It's
  133. important to free an ID when it's not in use, or they will consume
  134. memory unnecessarily.
  135.  
  136. =item free_wheel_id WHEEL_ID
  137.  
  138. Deallocates a wheel identifier so it may be reused later.  This often
  139. is called from a wheel's destructor.
  140.  
  141. =back
  142.  
  143. =head1 SEE ALSO
  144.  
  145. The SEE ALSO section in L<POE> contains a table of contents covering
  146. the entire POE distribution.
  147.  
  148. =head1 BUGS
  149.  
  150. It would be nice if wheels were more like proper Unix streams.
  151.  
  152. =head1 AUTHORS & COPYRIGHTS
  153.  
  154. Please see L<POE> for more information about authors and contributors.
  155.  
  156. =cut
  157.