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 / Driver.pm < prev    next >
Encoding:
Perl POD Document  |  2003-11-21  |  3.0 KB  |  108 lines
  1. # $Id: Driver.pm,v 1.15 2003/11/21 05:08:25 rcaputo Exp $
  2.  
  3. package POE::Driver;
  4.  
  5. use strict;
  6.  
  7. use vars qw($VERSION);
  8. $VERSION = do {my@r=(q$Revision: 1.15 $=~/\d+/g);sprintf"%d."."%04d"x$#r,@r};
  9.  
  10. use Carp qw(croak);
  11.  
  12. #------------------------------------------------------------------------------
  13.  
  14. sub new {
  15.   my $type = shift;
  16.   croak "$type is not meant to be used directly";
  17. }
  18.  
  19. #------------------------------------------------------------------------------
  20. 1;
  21.  
  22. __END__
  23.  
  24. =head1 NAME
  25.  
  26. POE::Driver - an abstract file driver
  27.  
  28. =head1 SYNOPSIS
  29.  
  30.   $driver = POE::Driver::Something->new();
  31.   $arrayref_of_data_chunks = $driver->get($filehandle);
  32.   $queue_octets = $driver->put($arrayref_of_data_chunks);
  33.   $queue_octets = $driver->flush($filehandle);
  34.   $queue_messages = $driver->get_out_messages_buffered();
  35.  
  36. =head1 DESCRIPTION
  37.  
  38. Drivers implement generic interfaces to low-level file I/O.  Wheels
  39. use them to read and write files, sockets, and other things without
  40. needing to know the details for doing so.
  41.  
  42. =head1 PUBLIC DRIVER METHODS
  43.  
  44. These methods are the generic Driver interface, and every driver must
  45. implement them.  Specific drivers may have additional methods.
  46.  
  47. =over 2
  48.  
  49. =item new
  50.  
  51. new() creates and initializes a new driver.  Specific drivers may have
  52. different constructor parameters.
  53.  
  54. =item get FILEHANDLE
  55.  
  56. get() immediately tries to read information from a filehandle.  It
  57. returns a reference to an array containing whatever it managed to
  58. read, or an empty array if nothing could be read.  It returns undef on
  59. error, and $! will be set.
  60.  
  61. The arrayref get() returns is suitable for passing to any
  62. POE::Filter's get() method.  This is exactly what the ReadWrite wheel
  63. does with it.
  64.  
  65. =item put ARRAYREF
  66.  
  67. put() places raw data chunks into the driver's output queue.  it
  68. accepts a reference to a list of raw data chunks, and it returns the
  69. number of octets remaining in its output queue.
  70.  
  71. Some drivers may flush data immediately from their put() methods.
  72.  
  73. =item flush FILEHANDLE
  74.  
  75. flush() attempts to flush some data from the driver's output queue to
  76. the FILEHANDLE.  It returns the number of octets remaining in the
  77. output queue after the flush attempt.
  78.  
  79. flush() does the physical write, counterpoint to get's read.  If
  80. flush() fails for any reason, $! will be set with the reason for its
  81. failure.  Otherwise $! will be zero.
  82.  
  83. =item get_out_messages_buffered
  84.  
  85. This data accessor returns the number of messages in the driver's
  86. output queue.  Partial messages are counted as whole ones.
  87.  
  88. =back
  89.  
  90. =head1 SEE ALSO
  91.  
  92. The SEE ALSO section in L<POE> contains a table of contents covering
  93. the entire POE distribution.
  94.  
  95. =head1 BUGS
  96.  
  97. There is no POE::Driver::SendRecv, but nobody has needed one so far.
  98.  
  99. In theory, drivers should be pretty much interchangeable.  In
  100. practice, there seems to be an impermeable barrier between the
  101. different SOCK_* types.
  102.  
  103. =head1 AUTHORS & COPYRIGHTS
  104.  
  105. Please see L<POE> for more information about authors and contributors.
  106.  
  107. =cut
  108.