Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Wheel::ReadWrite(User Contributed Perl DocumentatPOE::Wheel::ReadWrite(3)

NAME
       POE::Wheel::ReadWrite - non-blocking buffered I/O mix-in	for
       POE::Session

SYNOPSIS
	 #!perl

	 use warnings;
	 use strict;

	 use IO::Socket::INET;
	 use POE qw(Wheel::ReadWrite);

	 POE::Session->create(
	   inline_states => {
	     _start => sub {
	       # Note: IO::Socket::INET	will block.  We	recommend
	       # POE::Wheel::SocketFactory or POE::Component::Client::TCP if
	       # blocking is contraindicated.
	       $_[HEAP]{client}	= POE::Wheel::ReadWrite->new(
		 Handle	=> IO::Socket::INET->new(
		   PeerHost => 'www.yahoo.com',
		   PeerPort => 80,
		 ),
		 InputEvent => 'on_remote_data',
		 ErrorEvent => 'on_remote_fail',
	       );

	       print "Connected.  Sending request...\n";
	       $_[HEAP]{client}->put(
		 "GET /	HTTP/0.9",
		 "Host:	www.yahoo.com",
		 "",
	       );
	     },
	     on_remote_data => sub {
	       print "Received:	$_[ARG0]\n";
	     },
	     on_remote_fail => sub {
	       print "Connection failed	or ended.  Shutting down...\n";
	       delete $_[HEAP]{client};
	     },
	   },
	 );

	 POE::Kernel->run();
	 exit;

DESCRIPTION
       POE::Wheel::ReadWrite encapsulates a common design pattern: dealing
       with buffered I/O in a non-blocking, event driven fashion.

       The pattern goes	something like this:

       Given a filehandle, watch it for	incoming data.	When notified of
       incoming	data, read it, buffer it, and parse it according to some low-
       level protocol (such as line-by-line).  Generate	higher-level "here be
       lines" events, one per parsed line.

       In the other direction, accept whole chunks of data (such as lines) for
       output.	Reformat them according	to some	low-level protocol (such as by
       adding newlines), and buffer them for output.  Flush the	buffered data
       when the	filehandle is ready to transmit	it.

PUBLIC METHODS
   Constructor
       POE::Wheel subclasses tend to perform a lot of setup so that they run
       lighter and faster.  POE::Wheel::ReadWrite's constructor	is no
       exception.

       new

       new() creates and returns a new POE:Wheel::ReadWrite instance.  Under
       most circumstances, the wheel will continue to read/write to one	or
       more filehandles	until it's destroyed.

       Handle

       Handle defines the filehandle that a POE::Wheel::ReadWrite object will
       read from and write to.	The "SYNOPSIS" includes	an example using
       Handle.

       A single	POE::Wheel::ReadWrite object can read from and write to
       different filehandles.  See "InputHandle" for more information and an
       example.

       InputHandle

       InputHandle and OutputHandle may	be used	to specify different handles
       for input and output.  For example, input may be	from STDIN and output
       may go to STDOUT:

	 $_[HEAP]{console} = POE::Wheel::ReadWrite->new(
	   InputHandle => \*STDIN,
	   OutputHandle	=> \*STDOUT,
	   InputEvent => "console_input",
	 );

       InputHandle and OutputHandle may	not be used with Handle.

       OutputHandle

       InputHandle and OutputHandle may	be used	to specify different handles
       for input and output.  Please see "InputHandle" for more	information
       and an example.

       Driver

       Driver specifies	how POE::Wheel::ReadWrite will actually	read from and
       write to	its filehandle or filehandles.	Driver must be an object that
       inherits	from POE::Driver.

       POE::Driver::SysRW, which implements sysread() and syswrite(), is the
       default.	 It's used in nearly all cases,	so there's no point in
       specifying it.

       Filter

       Filter is the parser that POE::Wheel::ReadWrite will used to recognize
       input data and the serializer it	uses to	prepare	data for writing.  It
       defaults	to a new POE::Filter::Line instance since many network
       protocols are line based.

       InputFilter

       InputFilter and OutputFilter may	be used	to specify different filters
       for input and output.

       OutputFilter

       InputFilter and OutputFilter may	be used	to specify different filters
       for input and output. Please see	"InputFilter" for more information and
       an example.

       InputEvent

       InputEvent specifies the	name of	the event that will be sent for	every
       complete	input unit (as parsed by InputFilter or	Filter).

       Every input event includes two parameters:

       "ARG0" contains the parsed input	unit, and "ARG1" contains the unique
       ID for the POE::Wheel::ReadWrite	object that generated the event.

       InputEvent is optional.	If omitted, the	POE::Wheel::ReadWrite object
       will not	watch its Handle or InputHandle	for input, and no input	events
       will be generated.

       A sample	InputEvent handler:

	 sub handle_input {
	   my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
	   print "Echoing input	from wheel $wheel_id: $input\n";
	   $heap->{wheel}->put($input);	# Put... the input... beck!
	 }

       FlushedEvent

       FlushedEvent specifies the event	that a POE::Wheel::ReadWrite object
       will emit whenever its output buffer transitions	from containing	data
       to becoming empty.

       FlushedEvent comes with a single	parameter: "ARG0" contains the unique
       ID for the POE::Wheel::ReadWrite	object that generated the event.  This
       may be used to match the	event to a particular wheel.

       "Flushed" events	are often used to shut down I/O	after a	"goodbye"
       message has been	sent.  For example, the	following input_handler()
       responds	to "quit" by instructing the wheel to say "Goodbye." and then
       to send a "shutdown" event when that has	been flushed to	the socket.

	 sub handle_input {
	   my ($input, $wheel_id) = @_[ARG0, ARG1];
	   my $wheel = $_[HEAP]{wheel}{$wheel_id};

	   if ($input eq "quit") {
	     $wheel->event( FlushedEvent => "shutdown" );
	     $wheel->put("Goodbye.");
	   }
	   else	{
	     $wheel->put("Echo:	$input");
	   }
	 }

       Here's the shutdown handler.  It	just destroys the wheel	to end the
       connection:

	 sub handle_flushed {
	   my $wheel_id	= $_[ARG0];
	   delete $_[HEAP]{wheel}{$wheel_id};
	 }

       ErrorEvent

       ErrorEvent names	the event that a POE::Wheel::ReadWrite object will
       emit whenever an	error occurs.  Every ErrorEvent	includes four
       parameters:

       "ARG0" describes	what failed, either "read" or "write".	It doesn't
       name a particular function since	POE::Wheel::ReadWrite delegates	actual
       reading and writing to a	POE::Driver object.

       "ARG1" and "ARG2" hold numeric and string values	for $! at the time of
       failure.	 Applicatin code cannot	test $!	directly since its value may
       have changed between the	time of	the error and the time the error event
       is dispatched.

       "ARG3" contains the wheel's unique ID.  The wheel's ID is used to
       differentiate between many wheels managed by a single session.

       ErrorEvent may also indicate EOF	on a FileHandle	by returning operation
       "read" error 0.	For sockets, this means	the remote end has closed the
       connection.

       A sample	ErrorEvent handler:

	 sub error_state {
	   my ($operation, $errnum, $errstr, $id) = @_[ARG0..ARG3];
	   if ($operation eq "read" and	$errnum	== 0) {
	     print "EOF	from wheel $id\n";
	   }
	   else	{
	     warn "Wheel $id encountered $operation error $errnum: $errstr\n";
	   }
	   delete $_[HEAP]{wheels}{$id}; # shut	down that wheel
	 }

       HighEvent

       HighEvent and LowEvent are used along with HighMark and LowMark to
       control the flow	of streamed output.

       A HighEvent is sent when	the output buffer of a POE::Wheel::ReadWrite
       object exceeds a	certain	size (the "high	water" mark, or	HighMark).
       This advises an application to stop streaming output.  POE and Perl
       really don't care if the	application continues, but it's	possible that
       the process may run out of memory if a buffer grows without bounds.

       A POE::Wheel::ReadWrite object will continue to flush its buffer	even
       after an	application stops streaming data, until	the buffer is empty.
       Some streaming applications may require the buffer to always be primed
       with data, however.  For	example, a media server	would encounter
       stutters	if it waited for a FlushedEvent	before sending more data.

       LowEvent	solves the stutter problem.  A POE::Wheel::ReadWrite object
       will send a LowEvent when its output buffer drains below	a certain
       level (the "low water" mark, or LowMark).  This notifies	an application
       that the	buffer is small	enough that it may resume streaming.

       The stutter problem is solved because the output	buffer never quite
       reaches empty.

       HighEvent and LowEvent are edge-triggered, not level-triggered.	This
       means they are emitted once whenever a POE::Wheel::ReadWrite object's
       output buffer crosses the HighMark or LowMark.  If an application
       continues to put() data after the HighMark is reached, it will not
       cause another HighEvent to be sent.

       HighEvent is generally not needed.  The put() method will return	the
       high watermark state: true if the buffer	is at or above the high
       watermark, or false if the buffer has room for more data.  Here's a
       quick way to prime a POE::Wheel::ReadWrite object's output buffer:

	 1 while not $_[HEAP]{readwrite}->put(get_next_data());

       POE::Wheel::ReadWrite objects always start in a low-water state.

       HighEvent and LowEvent are optional.  Omit them if flow control is not
       needed.

       LowEvent

       HighEvent and LowEvent are used along with HighMark and LowMark to
       control the flow	of streamed output.  Please see	"HighEvent" for	more
       information and examples.

   put RECORDS
       put() accepts a list of RECORDS,	which will be serialized by the
       wheel's Filter and buffered and written by its Driver.

       put() returns true if a HighMark	has been set and the Driver's output
       buffer has reached or exceeded the limit.  False	is returned if
       HighMark	has not	been set, or if	the Driver's buffer is smaller than
       that limit.

       put()'s return value is purely advisory;	an application may continue
       buffering data beyond the HighMark---at the risk	of exceeding the
       process'	memory limits.	Do not use "<1 while not $wheel-"put()>>
       syntax if HighMark isn't	set: the application will fail spectacularly!

   event EVENT_TYPE => EVENT_NAME, ...
       event() allows an application to	modify the events emitted by a
       POE::Wheel::ReadWrite object.  All constructor parameters ending	in
       "Event" may be changed at run time: "InputEvent", "FlushedEvent",
       "ErrorEvent", "HighEvent", and "LowEvent".

       Setting an event	to undef will disable the code within the wheel	that
       generates the event.  So	for example, stopping InputEvent will also
       stop reading from the filehandle.  "pause_input"	and "resume_input" may
       be a better way to manage input events, however.

   set_filter POE_FILTER
       set_filter() changes the	way a POE::Wheel::ReadWrite object parses
       input and serializes output.  Any pending data that has not been
       dispatched to the application will be parsed with the new POE_FILTER.
       Information that	has been put() but not flushed will not	be
       reserialized.

       set_filter() performs the same act as calling set_input_filter()	and
       set_output_filter() with	the same POE::Filter object.

       Switching filters can be	tricky.	 Please	see the	discussion of
       get_pending() in	POE::Filter.  Some filters may not support being
       dynamically loaded or unloaded.

   set_input_filter POE_FILTER
       set_input_filter() changes a POE::Wheel::ReadWrite object's input
       filter while leaving the	output filter unchanged.  This alters the way
       data is parsed without affecting	how it's serialized for	output.

   set_output_filter POE_FILTER
       set_output_filter() changes how a POE::Wheel::ReadWrite object
       serializes its output but does not affect the way data is parsed.

   get_input_filter
       get_input_filter() returns the POE::Filter object currently used	by a
       POE::Wheel::ReadWrite object to parse incoming data.  The returned
       object may be introspected or altered via its own methods.

       There is	no get_filter()	method because there is	no sane	return value
       when input and output filters differ.

   get_output_filter
       get_output_filter() returns the POE::Filter object currently used by a
       POE::Wheel::ReadWrite object to serialize outgoing data.	 The returned
       object may be introspected or altered via its own methods.

       There is	no get_filter()	method because there is	no sane	return value
       when input and output filters differ.

   set_high_mark HIGH_MARK_OCTETS
       Sets the	high water mark---the number of	octets that designates a "full
       enough" output buffer.  A POE::Wheel::ReadWrite object will emit	a
       HighEvent when its output buffer	expands	to reach this point.  All
       put() calls will	return true when the output buffer is equal or greater
       than HIGH_MARK_OCTETS.

       Both HighEvent and put()	indicate that it's unsafe to continue writing
       when the	output buffer expands to at least HIGH_MARK_OCTETS.

   set_low_mark	LOW_MARK_OCTETS
       Sets the	low water mark---the number of octets that designates an
       "empty enough" output buffer.  This event lets an application know that
       it's safe to resume writing again.

       POE::Wheel::ReadWrite objects will emit a LowEvent when their output
       buffers shrink to LOW_MARK_OCTETS after having reached
       HIGH_MARK_OCTETS.

   ID
       ID() returns a POE::Wheel::ReadWrite object's unique ID.	 ID() is
       usually called after the	object is created so that the object may be
       stashed by its ID.  Events generated by the POE::Wheel::ReadWrite
       object will include the ID of the object, so that they may be matched
       back to their sources.

   pause_input
       pause_input() instructs a POE::Wheel::ReadWrite object to stop watching
       for input, and thus stop	emitting InputEvent events.  It's much more
       efficient than destroying the object outright, especially if an
       application intends to resume_input() later.

   resume_input
       resume_input() turns a POE::Wheel::ReadWrite object's input watcher
       back on.	 It's used to resume watching for input, and thus resume
       sending InputEvent events.  pause_input() and resume_input() implement
       a form of input flow control, driven by the application itself.

   get_input_handle
       get_input_handle() returns the filehandle being watched for input.

       Manipulating filehandles	that are managed by POE	may cause nasty	side
       effects,	which may change from one POE release to the next.  Please use
       caution.

   get_output_handle
       get_output_handle() returns the filehandle being	watched	for output.

       Manipulating filehandles	that are managed by POE	may cause nasty	side
       effects,	which may change from one POE release to the next.  Please use
       caution.

   shutdown_input
       Call shutdown($fh,0) on a POE::Wheel::ReadWrite object's	input
       filehandle.  This only works for	sockets; nothing will happen for other
       types of	filehandle.

       Occasionally, the POE::Wheel::ReadWrite object will stop	monitoring its
       input filehandle	for new	data.  This occurs regardless of the
       filehandle type.

   shutdown_output
       Call shutdown($fh,1) on a POE::Wheel::ReadWrite object's	output
       filehandle.  This only works for	sockets; nothing will happen for other
       types of	filehandle.

       Occasionally, the POE::Wheel::ReadWrite object will stop	monitoring its
       output filehandle for new data. This occurs regardless of the
       filehandle type.

   get_driver_out_octets
       POE::Driver objects contain output buffers that are flushed
       asynchronously.	get_driver_out_octets()	returns	the number of octets
       remaining in the	wheel's	driver's output	buffer.

   get_driver_out_messages
       POE::Driver objects' output buffers may be message based.  Every	put()
       call may	be buffered individually.  get_driver_out_messages() will
       return the number of pending put() messages that	remain to be sent.

       Stream-based drivers will simply	return 1 if any	data remains to	be
       flushed.	 This is because they operate with one potentially large
       message.

   flush
       flush() manually	attempts to flush a wheel's output in a	synchronous
       fashion.	 This can be used to flush small messages.  Note, however,
       that complete flushing is not guaranteed---to do	so would mean
       potentially blocking indefinitely, which	is undesirable in most POE
       applications.

       If an application must guarantee	a full buffer flush, it	may loop
       flush() calls:

	 $wheel->flush() while $wheel->get_driver_out_octets();

       However it would	be prudent to check for	errors as well.	 A flush()
       failure may be permanent, and an	infinite loop is probably not what
       most developers have in mind here.

       It should be obvious by now that	this method is experimental.  Its
       behavior	may change or it may disappear outright.  Please let us	know
       whether it's useful.

SEE ALSO
       POE::Wheel describes wheels in general.

       The SEE ALSO section in POE contains a table of contents	covering the
       entire POE distribution.

BUGS
       None known.

AUTHORS	& COPYRIGHTS
       Please see POE for more information about authors and contributors.

perl v5.32.0			  2020-02-01	      POE::Wheel::ReadWrite(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC METHODS | SEE ALSO | BUGS | AUTHORS & COPYRIGHTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Wheel::ReadWrite&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help