Permalink
Browse files

Documentation is hard!

  • Loading branch information...
1 parent acd2dc8 commit 3a579abeeca4ff685e2d69cc40fd3106ccd6e5f1 @rcaputo committed Aug 15, 1998
Showing with 346 additions and 94 deletions.
  1. +17 −12 lib/POE.pm
  2. +5 −2 lib/POE/Driver.pm
  3. +40 −8 lib/POE/Driver/SysRW.pm
  4. +41 −8 lib/POE/Filter/Line.pm
  5. +3 −3 lib/POE/Kernel.pm
  6. +114 −24 lib/POE/Session.pm
  7. +1 −1 lib/POE/Wheel.pm
  8. +115 −24 lib/POE/Wheel/ReadWrite.pm
  9. +10 −12 samples/selects.perl
View
@@ -31,19 +31,25 @@ POE - the Perl Operating Environment
=over 4
-=item POE::Kernel - main loop; select(2), signal, alarm, event services
-=item POE::Session - state machine managed by C<POE::Kernel>
+=item * POE::Kernel - main loop; select(2), signal, alarm, event services
-=item POE::Driver - abstract C<IO::Handle> driver
-=item POE::Driver::SysRW - C<sysread> and C<syswrite> on an C<IO::Handle>
+=item * POE::Session - state machine managed by C<POE::Kernel>
-=item POE::Filter - abstract raw E<lt>-E<gt> cooked stream translator
-=item POE::Filter::Line - break input into lines; add newlines to output
+=item * POE::Driver - abstract C<IO::Handle> driver
-=item POE::Wheel - extend C<POE::Session> by adding or removing event handlers
-=item POE::Wheel::ReadWrite - manage read/write states for a session
-=item POE::Wheel::ListenAccept - handle incoming TCP socket connections
-=item POE::Wheel::FollowTail - watch the end of a growing file
+=item * POE::Driver::SysRW - C<sysread> and C<syswrite> on an C<IO::Handle>
+
+=item * POE::Filter - abstract raw E<lt>-E<gt> cooked stream translator
+
+=item * POE::Filter::Line - break input into lines; add newlines to output
+
+=item * POE::Wheel - extend C<POE::Session> by adding or removing event handlers
+
+=item * POE::Wheel::ReadWrite - manage read/write states for a session
+
+=item * POE::Wheel::ListenAccept - handle incoming TCP socket connections
+
+=item * POE::Wheel::FollowTail - watch the end of a growing file (to be written)
=back
@@ -53,8 +59,7 @@ Please see the tests directory that comes with the POE bundle.
=head1 BUGS
-C<POE::Wheel> is in need of a new interface. Expect
-this part to change.
+None known.
=head1 CONTACT AND COPYRIGHT
View
@@ -1,7 +1,7 @@
# $Id$
# Documentation exists after __END__
-package Driver;
+package POE::Driver;
my $VERSION = 1.0;
@@ -24,7 +24,10 @@ POE::Driver - perform IO on a filehandle
=head1 SYNOPSIS
- $driver = new POE::Driver::Derivative();
+ $driver = new POE::Driver::Derivative(); # create a derivative driver
+ \@input_chunks = $driver->get($handle); # get data from $handle
+ $result = $driver->put($output_chunk); # put data into an output buffer
+ $result = $driver->flush($handle); # flush output buffer to $handle
=head1 DESCRIPTION
View
@@ -1,9 +1,10 @@
-###############################################################################
-# SysRW.pm - Documentation and Copyright are after __END__.
-###############################################################################
+# $Id$
+# Documentation exists after __END__
package POE::Driver::SysRW;
+my $VERSION = 1.0;
+
use strict;
use POSIX qw(EAGAIN);
@@ -49,7 +50,7 @@ sub get {
#------------------------------------------------------------------------------
sub flush {
- my ($self, $k, $handle) = @_;
+ my ($self, $handle) = @_;
# syswrite it, like we're supposed to
my $wrote_count = syswrite($handle,
$self->{'out queue'}->[0],
@@ -79,8 +80,39 @@ sub flush {
1;
__END__
-Documentation: to be
+=head1 NAME
+
+POE::Driver::SysRW - boilerplate sysread and syswrite
+
+=head1 SYNOPSIS
+
+ $sysrw = new POE::Driver::SysRW(); # create the SysRW driver
+ \@input_chunks = $sysrw->get($handle); # sysread from $handle
+ $result = $sysrw->put($output_chunk); # add chunk to output buffer
+ $result = $sysrw->flush($handle); # syswrite from output buffer
+
+=head1 DESCRIPTION
+
+Basic non-blocking sysread and syswrite with error checking and buffering that
+is compatible with C<POE::Kernel>'s non-blocking C<select(2)> logic. Ignores
+C<EAGAIN>.
+
+=head1 PUBLIC METHODS
+
+Please see C<POE::Driver> for explanations.
+
+=head1 EXAMPLES
+
+Please see tests/selects.perl for examples of C<POE::Driver::SysRW>.
+
+=head1 BUGS
+
+None known.
+
+=head1 CONTACT AND COPYRIGHT
+
+Copyright 1998 Rocco Caputo E<lt>troc@netrus.netE<gt>. All rights reserved.
+This program is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
-Copyright 1998 Rocco Caputo <troc@netrus.net>. All rights reserved.
-This is a pre-release version. Redistribution and modification are
-prohibited.
+=cut
View
@@ -1,12 +1,13 @@
-###############################################################################
-# SysRW.pm - Documentation and Copyright are after __END__.
-###############################################################################
+# $Id$
+# Documentation exists after __END__
package POE::Filter::Line;
+my $VERSION = 1.0;
+
use strict;
-###############################################################################
+#------------------------------------------------------------------------------
sub new {
my $type = shift;
@@ -39,8 +40,40 @@ sub put {
1;
__END__
-Documentation: to be
+=head1 NAME
+
+POE::Filter::Line - convert between line- and stream-based IO
+
+=head1 SYNOPSIS
+
+ $line = new POE::Filter::Line();
+
+ $line_with_crlf = $line->put("A line of text.");
+
+ $lines = $line->get("One\x0DTwo\x0AThree\x0D\x0AFour\x0A\x0DFive");
+ print join(':', @$lines), "\n";
+
+=head1 DESCRIPTION
+
+Breaks up a stream into lines, based on any permutation of CR/LF. Appends
+CR/LF to the ends of lines being sent.
+
+=head1 PUBLIC METHODS
+
+Please see C<POE::Filter> for explanations.
+
+=head1 EXAMPLES
+
+Please see tests/selects.perl for examples of C<POE::Filter::Line>.
+
+=head1 BUGS
+
+None known.
+
+=head1 CONTACT AND COPYRIGHT
+
+Copyright 1998 Rocco Caputo E<lt>troc@netrus.netE<gt>. All rights reserved.
+This program is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
-Copyright 1998 Rocco Caputo <troc@netrus.net>. All rights reserved.
-This is a pre-release version. Redistribution and modification are
-prohibited.
+=cut
View
@@ -1,9 +1,9 @@
-package POE::Kernel;
+# $Id$
+# Documentation exists after __END__
-# POD documentation exists after __END__
+package POE::Kernel;
my $VERSION = 1.0;
-my $rcs = '$Id$';
use strict;
use POSIX qw(EINPROGRESS EINTR);
Oops, something went wrong.

0 comments on commit 3a579ab

Please sign in to comment.