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

FreeBSD Manual Pages

  
 
  

home | help
Reflex::Role::Reading(User Contributed Perl DocumentatReflex::Role::Reading(3)

NAME
       Reflex::Role::Reading - add standard sysread() behavior to a class

VERSION
       This document describes version 0.100, released on April	02, 2017.

SYNOPSIS
       TODO - Changed again.

	       package InputStreaming;
	       use Reflex::Role;

	       attribute_parameter handle      => "handle";
	       callback_parameter  cb_data     => qw( on handle	data );
	       callback_parameter  cb_error    => qw( on handle	error );
	       callback_parameter  cb_closed   => qw( on handle	closed );
	       method_parameter	   method_stop => qw( stop handle _ );

	       role {
		       my $p = shift;

		       my $h	       = $p->handle();
		       my $cb_error    = $p->cb_error();
		       my $method_read = "on_${h}_readable";

		       method-emit_and_stop $cb_error => $p->ev_error();
       TODO - Changed.
		       with 'Reflex::Role::Reading' => {
			       handle	   => $h,
			       cb_data	   => $p->cb_data(),
			       cb_error	   => $cb_error,
			       cb_closed   => $p->cb_closed(),
			       method_read => $method_read,
		       };

		       with 'Reflex::Role::Readable' =>	{
			       handle	   => $h,
			       cb_ready	   => $method_read,
			       method_stop => $p->method_stop(),
		       };
	       };

	       1;

DESCRIPTION
       Reflex::Role::Readable implements a standard nonblocking	sysread()
       feature so that it may be added to classes as needed.

       There's a lot going on in the SYNOPSIS.

       Reflex::Role::Reading is	consumed to read from the InputStreaming
       handle.	The method named in $method_read is generated to read from the
       handle.	Three callbacks	may be triggered depending on the status
       returned	by sysread().  The "cb_data" callback will be invoked when
       data is read from the stream.  "cb_error" will be called	if there's a
       sysread() error.	 "cb_closed" will be triggered if the stream closes
       normally.

       Reflex::Role::Readable is consumed to watch the handle for activity.
       Its "cb_ready" is invoked whenever the handle has data to be read.
       "cb_ready" is Reflex::Role::Reading's "method_read", so data is read
       when it's ready.

   Attribute Role Parameters
       handle

       "handle"	names an attribute holding the handle to be watched for
       readable	data.

   Callback Role Parameters
       cb_closed

       "cb_closed" names the $self method that will be called whenever
       "handle"	has reached the	end of readable	data.  For sockets, this means
       the remote endpoint has closed or shutdown for writing.

       "cb_closed" is by default the catenation	of "on_", the "handle" name,
       and "_closed".  A handle	named "XYZ" will by default trigger
       on_XYZ_closed() callbacks.  The role defines a default callback that
       will emit a "closed" event and call stopped(), which is provided	by
       Reflex::Role::Collectible.

       Currently the second parameter to the "cb_closed" callback contains no
       parameters of note.

       When overriding this callback, please be	sure to	call stopped(),	which
       is provided by Reflex::Role::Collectible.  Calling stopped() is vital
       for collectible objects to be released from memory when managed by
       Reflex::Collection.

       cb_data

       "cb_data" names the $self method	that will be called whenever the
       stream for "handle" has provided	new data.  By default, it's the
       catenation of "on_", the	"handle" name, and "_data".  A handle named
       "XYZ" will by default trigger on_XYZ_data() callbacks.  The role
       defines a default callback that will emit a "data" event	with
       cb_data()'s parameters.

       All Reflex parameterized	role calblacks are invoked with	two
       parameters: $self and an	anonymous hashref of named values specific to
       the callback.  "cb_data"	callbacks include a single named value,
       "data", that contains the raw octets received from the filehandle.

       cb_error

       "cb_error" names	the $self method that will be called whenever the
       stream produces an error.  By default, this method will be the
       catenation of "on_", the	"handle" name, and "_error".  As in
       on_XYZ_error(), if the handle is	named "XYZ".  The role defines a
       default callback	that will emit an "error" event	with cb_error()'s
       parameters, then	will call stopped() so that streams managed by
       Reflex::Collection will be automatically	cleaned	up after stopping.

       "cb_error" callbacks receive two	parameters, $self and an anonymous
       hashref of named	values specific	to the callback.  Reflex error
       callbacks include three standard	values.	 "errfun" contains a single
       word description	of the function	that failed.  "errnum" contains	the
       numeric value of	$! at the time of failure.  "errstr" holds the
       stringified version of $!.

       Values of $! are	passed as parameters since the global variable may
       change before the callback can be invoked.

       When overriding this callback, please be	sure to	call stopped(),	which
       is provided by Reflex::Role::Collectible.  Calling stopped() is vital
       for collectible objects to be released from memory when managed by
       Reflex::Collection.

   Method Role Parameters
       method_read

       This role genrates a method to read from	the handle in the attribute
       named in	its "handle" role parameter.  The "method_read"	role parameter
       defines the name	for this generated read	method.	 By default, the read
       method is named after tha handle's attribute: "read_${$handle_name}".

EXAMPLES
       TODO - I'm sure there are some.

SEE ALSO
       Please see those	modules/websites for more information related to this
       module.

       o   Reflex

       o   Reflex

       o   Reflex::Role

       o   Reflex::Role::Writing

       o   Reflex::Role::Readable

       o   Reflex::Role::Streaming

       o   "ACKNOWLEDGEMENTS" in Reflex

       o   "ASSISTANCE"	in Reflex

       o   "AUTHORS" in	Reflex

       o   "BUGS" in Reflex

       o   "BUGS" in Reflex

       o   "CONTRIBUTORS" in Reflex

       o   "COPYRIGHT" in Reflex

       o   "LICENSE" in	Reflex

       o   "TODO" in Reflex

BUGS AND LIMITATIONS
       You can make new	bug reports, and view existing ones, through the web
       interface at <http://rt.cpan.org/Public/Dist/Display.html?Name=Reflex>.

AUTHOR
       Rocco Caputo <rcaputo@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2017 by Rocco Caputo.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

AVAILABILITY
       The latest version of this module is available from the Comprehensive
       Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find
       a CPAN site near	you, or	see <https://metacpan.org/module/Reflex/>.

DISCLAIMER OF WARRANTY
       BECAUSE THIS SOFTWARE IS	LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
       FOR THE SOFTWARE, TO THE	EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
       WHEN OTHERWISE STATED IN	WRITING	THE COPYRIGHT HOLDERS AND/OR OTHER
       PARTIES PROVIDE THE SOFTWARE "AS	IS" WITHOUT WARRANTY OF	ANY KIND,
       EITHER EXPRESSED	OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF	THE SOFTWARE IS	WITH
       YOU. SHOULD THE SOFTWARE	PROVE DEFECTIVE, YOU ASSUME THE	COST OF	ALL
       NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR	AGREED TO IN WRITING
       WILL ANY	COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
       REDISTRIBUTE THE	SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
       CONSEQUENTIAL DAMAGES ARISING OUT OF THE	USE OR INABILITY TO USE	THE
       SOFTWARE	(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
       RENDERED	INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGES.

perl v5.32.0			  2017-04-02	      Reflex::Role::Reading(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | BUGS AND LIMITATIONS | AUTHOR | COPYRIGHT AND LICENSE | AVAILABILITY | DISCLAIMER OF WARRANTY

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

home | help