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

FreeBSD Manual Pages

  
 
  

home | help
fileevent(3)	      User Contributed Perl Documentation	  fileevent(3)

NAME
       Tk::fileevent - Execute a callback when a filehandle becomes readable
       or writable

SYNOPSIS
       $widget->fileevent(fileHandle,readable?,callback?)

       $widget->fileevent(fileHandle,writable?,callback?)

DESCRIPTION
       This command is used to create file event handlers.  A file event
       handler is a binding between a filehandle and a callback, such that the
       callback	is evaluated whenever the filehandle becomes readable or
       writable.  File event handlers are most commonly	used to	allow data to
       be received from	another	process	on an event-driven basis, so that the
       receiver	can continue to	interact with the user while waiting for the
       data to arrive.	If an application invokes "<>",	"sysread" or "read" on
       a blocking filehandle when there	is no input data available, the
       process will block; until the input data	arrives, it will not be	able
       to service other	events,	so it will appear to the user to ``freeze
       up''.  With fileevent, the process can tell when	data is	present	and
       only invoke gets	or read	when they won't	block.

       The fileHandle argument to fileevent refers to an open filehandle, such
       as the return value from	a previous open	or socket command.  If the
       callback	argument is specified, then fileevent creates a	new event
       handler:	 callback will be evaluated whenever the filehandle becomes
       readable	or writable (depending on the argument to fileevent).  In this
       case fileevent returns an empty string.	The readable and writable
       event handlers for a file are independent, and may be created and
       deleted separately.  However, there may be at most one readable and one
       writable	handler	for a file at a	given time in a	given interpreter.  If
       fileevent is called when	the specified handler already exists in	the
       invoking	interpreter, the new callback replaces the old one.

       If the callback argument	is not specified, fileevent returns the
       current callback	for fileHandle,	or an empty string if there is none.
       If the callback argument	is specified as	an empty string	then the event
       handler is deleted, so that no callback will be invoked.	 A file	event
       handler is also deleted automatically whenever its filehandle is	closed
       or its interpreter is deleted.

       A filehandle is considered to be	readable if there is unread data
       available on the	underlying device.  A filehandle is also considered to
       be readable if an end of	file or	error condition	is present on the
       underlying file or device.  It is important for callback	to check for
       these conditions	and handle them	appropriately;	for example, if	there
       is no special check for end of file, an infinite	loop may occur where
       callback	reads no data, returns,	and is immediately invoked again.

       A filehandle is considered to be	writable if at least one byte of data
       can be written to the underlying	file or	device without blocking, or if
       an error	condition is present on	the underlying file or device.

       Event-driven I/O	works best for filehandles that	have been placed into
       nonblocking mode.  In blocking mode, a "print" command may block	if you
       give it more data than the underlying file or device can	accept,	and a
       "<>", "sysread" or "read" command will block if you attempt to read
       more data than is ready;	 no events will	be processed while the
       commands	block.	In nonblocking mode "print", "<>", "sysread" and
       "read" never block.  See	the documentation for the individual commands
       for information on how they handle blocking and nonblocking
       filehandles.

       The callback for	a file event is	executed in the	context	of $widget
       with which fileevent was	invoked.  If an	error occurs while executing
       the callback then the Tk::Error mechanism is used to report the error.
       In addition, the	file event handler is deleted if it ever returns an
       error;  this is done in order to	prevent	infinite loops due to buggy
       handlers.

BUGS
       On windows platforms fileevent is limited in the	types of filehandles
       that behave correctly. Making filefhandles non-blocking is only
       implemented on a	subset of UNIX platforms (see Tk::IO).

CREDITS
       fileevent is based on the addinput command created by Mark Diekhans.

SEE ALSO
       Tk::IO Tk::callbacks

KEYWORDS
       asynchronous I/O, blocking, filehandle, event handler, nonblocking,
       readable, callback, writable.

perl v5.24.1			  2013-11-15			  fileevent(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS | CREDITS | SEE ALSO | KEYWORDS

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

home | help