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

FreeBSD Manual Pages

  
 
  

home | help
pod::Prima::File(3)   User Contributed Perl Documentation  pod::Prima::File(3)

NAME
       Prima::File - asynchronous stream I/O.

SYNOPSIS
	 use strict;
	 use Prima qw(Application);

	 # create pipe and autoflush the writer	end
	 pipe(READ, WRITE) or die "pipe():$!\n";
	 select	WRITE;
	 $|=1;
	 select	STDOUT;

	 # create Prima	listener on the	reader end
	 my $read = Prima::File-> new(
	     file => \*READ,
	     mask => fe::Read,
	     onRead => sub {
		$_ = <READ>;
		print "read:$_\n";
	     },
	 );

	 print WRITE "line\n";
	 run Prima;

DESCRIPTION
       Prima::File provides access to the I/O stream events, that are called
       when a file handle becomes readable, writable or	if an exception
       occurred. Registering file handles to Prima::File objects makes
       possible	the stream operations coexist with the event loop.

USAGE
       Prima::File is a	descendant of Prima::Component.	 Objects of
       Prima::File class must be binded	to a valid file	handle object, before
       the associated events can occur:

	 my $f = Prima::File-> create();
	 $f-> file( *STDIN);

       When a file handle, binded via the "::file" property becomes readable,
       writable	or when	an exception signaled, one of three correspondent
       events called - "Read", "Write" or "Exception". When a handle is	always
       readable, or always writable, or, some of these events are desired to
       be blocked, the file event mask can be set via the "::mask" property:

	 $f-> mask( fe::Read | fe::Exception);

       NB. Due to different system implementations, the	only handles,
       currently supported on all systems, are socket handle and disk file
       handles.	Pipes only work	on unix	platforms. The example file socket.pl
       elucidates the use of sockets together with Prima::File.

       When a file handle is not needed	anymore, it is expected	to be detached
       from an object explicitly:

	 $f-> file( undef);

       However,	if the system detects that a file handle is no longer valid,
       it is automatically detached. It	is possible to check, if a file	handle
       is still	valid by calling the "is_active()" method.

       Prima::File events are basically	the same I/O callbacks,	provided by a
       system "select()" call. See documentation of your system's select() for
       the implementation details.

API
   Properties
       file HANDLE
	   Selects a file handle, that is to be	monitored for stream I/O
	   events.  If HANDLE is "undef", object is returned to	a passive
	   state, and the previously binded file handle	is de-selected.

       fd INTEGER
	   Same	as file(), but to be used for file descriptiors. When this
	   property is used, consequent	get-calls to file() will return	undef.

       mask EVENT_MASK
	   Selects a event mask, that is a combination of "fe::XXX" integer
	   constants, each representing	an event:

	      fe::Read
	      fe::Write
	      fe::Exception

	   The omitted events are effectively excluded from the	system file
	   event multiplexing mechanism.

   Methods
       get_handle
	   Returns "sprintf("0x%08x", fileno( file ))" string.	If "::file" is
	   "undef", -1 is used instead fileno()	result.

       is_active AUTODETACH = 0
	   Returns a boolean flag, indicating if a file	handle is valid.  If
	   AUTODETACH is 1, and	the file handle	is not valid, "file(undef)" is
	   called.

   Events
       Read
	   Called when a file handle becomes readable. The callback procedure
	   is expected to call a non-blocking read() on	the file handle.

       Write
	   Called when a file handle becomes writable. The callback procedure
	   is expected to call a non-blocking write() on the file handle.

       Exception
	   Called when an exception is signaled	on a file handle.  The
	   exceptions are specific to handle type and the operating system.
	   For example,	a unix socket signals "Exception" when a control
	   status data for a pseudo terminal or	an out-of-band data arrives.

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO
       Prima, Prima::Object

perl v5.24.1			  2017-02-28		   pod::Prima::File(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | API | AUTHOR | SEE ALSO

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

home | help