.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "AtExit 3" .TH AtExit 3 "1999-01-20" "perl v5.8.4" "User Contributed Perl Documentation" .SH "NAME" \&\fBatexit\fR, \fBAtExit\fR \-\- perform exit processing for a program or object .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use AtExit; .Ve .PP .Vb 4 \& sub cleanup { \& my @args = @_; \& print "cleanup() executing: args = @args\en"; \& } .Ve .PP .Vb 1 \& ## Register subroutines to be called when this program exits .Ve .PP .Vb 2 \& $_ = atexit(\e&cleanup, "This call was registered first"); \& print "first call to atexit() returned $_\en"; .Ve .PP .Vb 2 \& $_ = atexit("cleanup", "This call was registered second"); \& print "second call to atexit() returned $_\en"; .Ve .PP .Vb 2 \& $_ = atexit("cleanup", "This call should've been unregistered by rmexit"); \& rmexit($_) or warn "couldnt' unregister exit-sub $_!"; .Ve .PP .Vb 10 \& if (@ARGV == 0) { \& ## Register subroutines to be called when this lexical scope is exited \& my $scope1 = AtExit->new( \e&cleanup, "Scope 1, Callback 1" ); \& { \& ## Do the same for this nested scope \& my $scope2 = AtExit->new; \& $_ = $scope2->atexit( \e&cleanup, "Scope 2, Callback 1" ); \& $scope1->atexit( \e&cleanup, "Scope 1, Callback 2"); \& $scope2->atexit( \e&cleanup, "Scope 2, Callback 2" ); \& $scope2->rmexit($_) or warn "couldn't unregister exit-sub $_!"; .Ve .PP .Vb 6 \& print "*** Leaving Scope 2 ***\en"; \& } \& print "*** Finished Scope 2 ***\en"; \& print "*** Leaving Scope 1 ***\en"; \& } \& print "*** Finished Scope 1 ***\en" if (@ARGV == 0); .Ve .PP .Vb 3 \& END { \& print "*** Now performing program-exit processing ***\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBAtExit\fR module provides ANSI-C style exit processing modeled after the \f(CW\*(C`atexit\*(C'\fR function in the standard C library (see atexit(3C)). Various exit processing routines may be registered by calling \&\fBatexit\fR and passing it the desired subroutine along with any desired arguments. Then, at program-exit time, the subroutines registered with \fBatexit\fR are invoked with their given arguments in the \&\fIreverse\fR order of registration (last one registered is invoked first). Registering the same subroutine more than once will cause that subroutine to be invoked once for each registration. .PP An \fBAtExit\fR object can be created in any scope. When invoked as a function, \fBatexit\fR registers callbacks to be executed at \fIprogram-exit\fR time. But when invoked as an object-method (using the \f(CW\*(C`$object\->method_name\*(C'\fR syntax), callbacks registered with an \fBAtExit\fR object are executed at \&\fIobject-destruction time\fR! The rules for order of execution of the registered subroutines are the same for objects during object\-destruction, as for the program during program\-termination. .PP The \fBatexit\fR function/method should be passed a subroutine name or reference, optionally followed by the list of arguments with which to invoke it at program/object exit time. Anonymous subroutine references passed to \fBatexit\fR act as \*(L"closures\*(R" (which are described in perlref). If a subroutine \fIname\fR is specified (as opposed to a subroutine reference) then, unless the subroutine name has an explicit package prefix, it is assumed to be the name of a subroutine in the caller's current package. A reference to the specified subroutine is obtained, and, if invocation arguments were specified, it is \*(L"wrapped up\*(R" in a closure which invokes the subroutine with the specified arguments. The resulting subroutine reference is added to the front of the list of exit-handling subroutines for the program (\f(CW\*(C`atexit\*(C'\fR) or the \fBAtExit\fR object (\f(CW\*(C`$exitObject\->atexit\*(C'\fR) and the reference is then returned to the caller (just in case you might want to unregister it later using \fBrmexit\fR. If the given subroutine could \fInot\fR be registered, then the value zero is returned. .PP The \fBrmexit\fR function/method should be passed one or more subroutine references, each of which was returned by a previous call to \&\fBatexit\fR. For each argument given, \fBrmexit\fR will look in the list of exit-handling subroutines for the program (\fBrmexit\fR) or the \&\fBAtExit\fR object (\f(CW\*(C`$exitObject\->rmexit\*(C'\fR) and remove the first matching entry from the list. If no arguments are given, \&\fIthen all program or object exit-handlers are unregistered!\fR The value returned will be the number of subroutines that were successfully unregistered. .PP At object destruction time, the \f(CW\*(C`DESTROY{}\*(C'\fR subroutine in the \&\fBAtExit\fR module iterates over the subroutine references in the \&\fBAtExit\fR object and invokes each one in turn (each subroutine is removed from the front of the queue immediately before it is invoked). At program-exit time, the \f(CW\*(C`END{}\*(C'\fR block in the \fBAtExit\fR module iterates over the subroutines in the array returned by the \&\fBexit_subs\fR method and invokes each one in turn (each subroutine is removed from the front of the queue immediately before it is invoked). Note that in both cases (program\-exit, and object\-destruction) the subroutines in this queue are invoked in first-to-last order (the \&\fIreverse\fR order in which they were registered with \fBatexit\fR). .Sh "Adding and removing callbacks during exit/destruction time." .IX Subsection "Adding and removing callbacks during exit/destruction time." The method \fBignore_when_exiting\fR specifies how exit-callback registration and unregistration will be handled during program-exit or object-destruction time, while exit-callbacks are in process of being invoked. .PP When invoked as a class method (e.g., \f(CW\*(C`AtExit\->ignore_when_exiting\*(C'\fR), \&\fBignore_when_exiting\fR corresponds to the handling of calls to \&\fBatexit\fR and \fBrmexit\fR during program\-termination. But when invoked as an \fIobject\fR method (e.g., \f(CW\*(C`$exitObject\->ignore_when_exiting\*(C'\fR), then \&\fBignore_when_exiting\fR corresponds to the handling of calls to \&\fBatexit\fR and \fBrmexit\fR during \fIobject-destruction\fR for the particular object. .PP By default, \fBignore_when_exiting\fR returns a non-zero value, which causes \fBatexit\fR to \fIignore\fR any calls made to it during this time (a value of zero will be returned). This behavior is consistent with that of the standard C library function of the same name. If desired however, the user may enable the registration of subroutines by \&\fBatexit\fR during this time by invoking \fBignore_when_exiting\fR and passing it an argument of 0, \f(CW""\fR, or \f(CW\*(C`undef\*(C'\fR (for example, \&\f(CW\*(C`AtExit\->ignore_when_exiting(0)\*(C'\fR or \&\f(CW\*(C`$exitObject\->ignore_when_exiting(0)\*(C'\fR, Just remember that any subroutines registered with \fBatexit\fR be placed at the \fIfront\fR of the queue of yet-to-be-invoked exit-processing subroutines for the program (\fBatexit\fR) or the \&\fBAtExit\fR object (\f(CW\*(C`$exitObject\->atexit\*(C'\fR). .PP Regardless of when it is invoked, \fBrmexit\fR will \fIalways\fR attempt to unregister the given subroutines (even when called during program/object exit processing). Keep in mind however that if it is invoked during program/object exit then it will \fIfail\fR to unregister any subroutines that have \fIalready been invoked\fR (since those subroutine calls have already been removed from the corresponding list of exit-handling subroutines). .PP The method \fBis_exiting\fR may consulted examined to determine if routines registered using \fBatexit\fR are currently in the process of being invoked. It will be non-zero if they are and zero otherwise. When invoked as a class method (e.g., \f(CW\*(C`AtExit\->is_exiting\*(C'\fR), the return value will correspond to program-exit processing; but when invoked as an \fIobject\fR method (e.g., \f(CW\*(C`$exitObject\->is_exiting\*(C'\fR) the return value will correspond to object-destruction processing for the given object. .PP If, for any reason, the list of registered callback needs to be directly accessed or manipulated, the \fBexit_subs\fR function will return a reference to the list of program-exit callbacks. When invoked as a method, \fBexit_subs\fR will return a reference to the list of object-destruction callbacks for the corresponding object. .SH "EXPORTS" .IX Header "EXPORTS" For backward compatibility, \fBatexit\fR and \fBrmexit\fR are exported by default. \fINote\fR however that \fBexit_subs\fR, \fBis_exiting\fR, and \&\fBignore_when_exiting\fR are \fInot\fR exported by default, and should be invoked as class methods (e.g. \f(CW\*(C`AtExit\->is_exiting\*(C'\fR) if they are to manipulate program-exit information (rather than object\-destruction) and not explicitly imported. .SH "CAVEATS" .IX Header "CAVEATS" .SH "Program-termination and Object-destruction" .IX Header "Program-termination and Object-destruction" The usual Perl way of doing program/module\-exit processing is through the use of \f(CW\*(C`END{}\*(C'\fR blocks (see \*(L"Package Constructors and Destructors\*(R" in perlmod). The \fBAtExit\fR module implements its program-exit processing with with an \f(CW\*(C`END{}\*(C'\fR block that invokes all the subroutines registered by \&\fBatexit\fR in the array whose referenced is returned by \f(CW\*(C`exit_subs\*(C'\fR. .PP For an object, object-destruction processing is implemented by having the \&\f(CW\*(C`DESTROY\*(C'\fR method for the object invoke all the subroutines registered by \f(CW\*(C`$exitObject\->atexit\*(C'\fR. This occurs when the object loses it's last reference, which is not necessarily at program end time. .PP For objects defined in the global context, if any other \f(CW\*(C`END{}\*(C'\fR block processing is specified in the user's code or in any other packages it uses, then the order in which the exit processing takes place is subject to Perl's rules for the order in which objects loose their last references and \f(CW\*(C`END{}\*(C'\fR blocks are processed. This may affect when subroutines registered with \fBatexit\fR are invoked with respect to other exit processing that is to be performed. In particular, if \fBrmexit\fR is invoked from within an \f(CW\*(C`END{}\*(C'\fR block that executes \fIafter\fR the \&\fBAtExit\fR object was destroyed, then the corresponding subroutine will not be registered and will never be invoked by the \fBAtExit\fR module's destructor code. .ie n .SH """END{}"" block processing order" .el .SH "\f(CWEND{}\fP block processing order" .IX Header "END{} block processing order" \&\f(CW\*(C`END{}\*(C'\fR blocks, including those in other packages, get called in the reverse order in which they appear in the code. (\fBatexit\fR subroutines get called in the reverse order in which they are registered.) If a package gets read via \*(L"use\*(R", it will act as if the \f(CW\*(C`END{}\*(C'\fR block was defined at that particular part of the \*(L"main\*(R" code. Packages read via \&\*(L"require\*(R" will be executed after the code of \*(L"main\*(R" has been parsed and will be seen last so will execute first (they get executed in the context of the package in which they exist). .PP It is important to note that \f(CW\*(C`END{}\*(C'\fR blocks and object destruction only get called on normal termination (which includes calls to \fBdie\fR or \fBCarp::croak\fR). They do \fInot\fR get called when the program terminates \fIabnormally\fR (due to a signal for example) unless special arrangements have been made by the programmer (e.g. using a signal handler \*(-- see \*(L"%SIG{expr}\*(R" in perlvar). .SH "SEE ALSO" .IX Header "SEE ALSO" atexit(3C) describes the \fBatexit\fR function for the standard C library (the actual Unix manual section in which it appears may differ from platform to platform \- try sections 3C, 3, 2C, and 2). Further information on anonymous subroutines (\*(L"closures\*(R") may be found in perlref. For more information on \f(CW\*(C`END{}\*(C'\fR blocks, see \&\*(L"Package Constructors and Destructors\*(R" in perlmod. See \&\*(L"%SIG{expr}\*(R" in perlvar for handling abnormal program termination. .SH "AUTHOR" .IX Header "AUTHOR" Andrew Langmead (initial draft). .PP Brad Appleton (Version 1.02 and 2.00). .PP Michael A. Chase (Version 2.00).