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

FreeBSD Manual Pages

  
 
  

home | help
Alarm::Concurrent(3)  User Contributed Perl Documentation Alarm::Concurrent(3)

NAME
       Alarm::Concurrent - Allow multiple, concurrent alarms.

DESCRIPTION
       This module is an attempt to enhance Perl's built-in alarm/$SIG{ALRM}
       functionality.

       This function, and its associated signal	handler, allow you to arrange
       for your	program	to receive a SIGALRM signal, which you can then	catch
       and deal	with appropriately.

       Unfortunately, due to the nature	of the design of these signals (at the
       OS level), you can only have one	alarm and handler active at any	given
       time.  That's where this	module comes in.

       This module allows you to define	multiple alarms, each with an
       associated handler.  These alarms are sequenced (in a queue) but
       concurrent, which means that their order	is preserved but they always
       go off as their set time	expires, regardless of the state of the	other
       alarms.	(If you'd like to have the alarms only go off in the order you
       set them, see Alarm::Queued.)

       To set an alarm,	call the "setalarm()" function with the	set time of
       the alarm and a reference to the	subroutine to be called	when the alarm
       goes off.  You can then go on with your program and the alarm will be
       called after the	set time has passed.

       It is also possible to set an alarm that	does not have a	handler
       associated with it using	"Alarm::Concurrent::alarm()".  (This function
       can also	be imported into your namespace, in which case it will replace
       Perl's built-in alarm for your package only.)

       If an alarm that	does not have a	handler	associated with	it goes	off,
       the default handler, pointed to by $Alarm::Concurrent::DEFAULT_HANLDER,
       is called.  You can change the default handler by assigning to this
       variable.

       The default $Alarm::Concurrent::DEFAULT_HANDLER simply dies with	the
       message "Alarm clock!\n".

IMPORT/EXPORT
       No methods are exported by default but you can import any of the
       functions in the	FUNCTIONS section.

       You can also import the special tag ":ALL" which	will import all	the
       functions in the	FUNCTIONS section (except
       "Alarm::Concurrent::restore()").

OVERRIDE
       If you import the special tag ":OVERRIDE", this module will override
       Perl's built-in alarm function for every	namespace and it will take
       over Perl's magic %SIG variable,	changing any attempts to read or write
       $SIG{ALRM} into calls to	"gethandler()" and "sethandler()",
       respectively (reading and writing to other keys in %SIG is unaffected).

       This can	be useful when you are calling code that tries to set its own
       alarm "the old fashioned	way."  It can also, however, be	dangerous.
       Overriding alarm	is documented and should be stable but taking over
       %SIG is more risky (see CAVEATS).

       Note that if you	do not override	alarm and %SIG,	any code you use that
       sets "legacy alarms" will disable all of	your concurrent	alarms.	 You
       can call	"Alarm::Concurrent::restore()" to reinstall the
       Alarm::Concurrent handler.  This	function can not be imported.

FUNCTIONS
       The following functions are available for use.

       setalarm	SECONDS	CODEREF
	   Sets	a new alarm and	associates a handler with it.  The handler is
	   called when the specified number of seconds have elapsed.  See
	   DESCRIPTION for more	information.

       clearalarm INDEX	LENGTH
       clearalarm INDEX
       clearalarm
	   Clears one or more previously set alarms.  The index	is an array
	   index, with 0 being the currently active alarm and -1 being the
	   last	(most recent) alarm that was set.

	   INDEX defaults to 0 and LENGTH defaults to 1.

       alarm SECONDS
       alarm
	   Creates a new alarm with no handler.	 A handler can later be	set
	   for it via sethandler() or $SIG{ALRM}, if overridden.

	   For the most	part, this function behaves exactly like Perl's	built-
	   in alarm function, except that it sets up a concurrent alarm
	   instead.  Thus, each	call to	alarm does not disable previous	alarms
	   unless called with a	set time of 0.

	   Calling "alarm()" with a set	time of	0 will disable the last	alarm
	   set.

	   If SECONDS is not specified,	the value stored in $_ is used.

       sethandler INDEX	CODEREF
       sethandler CODEREF
	   Sets	a handler for the alarm	found at INDEX in the queue.  This is
	   an array index, so negative values may be used to indicate position
	   relative to the end of the queue.

	   If INDEX is not specified, the handler is set for the last alarm in
	   the queue that doesn't have one associated with it.	This means
	   that	if you set multiple alarms using "alarm()", you	should arrange
	   their respective "sethandler()"'s in	the opposite order.

       gethandler INDEX
       gethandler
	   Returns the handler for the alarm found at INDEX in the queue.
	   This	is an array index, so negative values may be used.

	   If INDEX is not specified, returns the handler for the currently
	   active alarm.

       restore FLAG
       restore
	   This	function reinstalls the	Alarm::Concurrent alarm	handler	if it
	   has been replaced by	a "legacy alarm	handler."

	   If FLAG is present and true,	"restore()" will save the current
	   handler by setting it as a new concurrent alarm (as if you had
	   called "setalarm()" for it).

	   This	function may not be imported.

	   Note:  Do not call this function if you have	imported the
	   ":OVERLOAD" symbol.	It can have unpredictable results.

CAVEATS
       o   %SIG	is Perl	magic and should probably not be messed	with, though I
	   have	not witnessed any problems in the (admittedly limited) testing
	   I've	done.  I would be interested to	hear from anyone who performs
	   extensive testing, with different versions of Perl, of the
	   reliability of doing	this.

	   Moreover, since there is no way to just take	over $SIG{ALRM}, the
	   entire magic	hash is	usurped	and any	other "%SIG}" accesses are
	   simply passed through to the	original magic hash.  This means that
	   if there are	any problems, they will	most likely affect all other
	   signal handlers you have defined, including $SIG{__WARN__} and
	   $SIG{__DIE__} and others.

	   In other words, if you're going to use the ":OVERRIDE" option, you
	   do so at your own risk (and you'd better be pretty damn sure	of
	   yourself, too).

       o   The default $DEFAULT_HANDLER	simply dies with the message "Alarm
	   clock!\n".

       o   All warnings	about alarms possibly being off	by up to a full	second
	   still apply.	 See the documentation for alarm for more information.

       o   The alarm handling routine does not make any	allowances for systems
	   that	clear the alarm	handler	before it is called.  This may be
	   changed in the future.

       o   According to	"Signals" in perlipc, doing just about anything	in
	   signal handling routines is dangerous because it might be called
	   during a non-re-entrant system library routines which could cause a
	   memory fault	and core dump.

	   The Alarm::Concurrent alarm handling	routine	does quite a bit.

	   You have been warned.

AUTHOR
       Written by Cory Johns (c) 2001.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 396:
	   You forgot a	'=back'	before '=head1'

perl v5.24.1			  2017-07-03		  Alarm::Concurrent(3)

NAME | DESCRIPTION | IMPORT/EXPORT | OVERRIDE | FUNCTIONS | CAVEATS | AUTHOR | POD ERRORS

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

home | help