summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/lib.tex1
-rw-r--r--Doc/lib/libatexit.tex59
-rw-r--r--Doc/lib/libsys.tex4
3 files changed, 63 insertions, 1 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index b426a6a..3e60b9b 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -73,6 +73,7 @@ and how to embed it in other applications.
\input{libpython} % Python Services
\input{libsys}
+\input{libatexit}
\input{libtypes}
\input{libuserdict}
\input{liboperator}
diff --git a/Doc/lib/libatexit.tex b/Doc/lib/libatexit.tex
new file mode 100644
index 0000000..9d0b48c
--- /dev/null
+++ b/Doc/lib/libatexit.tex
@@ -0,0 +1,59 @@
+\section{\module{atexit} ---
+ exit handlers}
+
+\declaremodule{standard}{atexit}
+\moduleauthor{Skip Montanaro}{skip@mojam.com}
+\sectionauthor{Skip Montanaro}{skip@mojam.com}
+\modulesynopsis{Register and execute cleanup functions.}
+
+The \module{atexit} module defines a single function to register
+cleanup functions. Functions thus registered are automatically
+executed upon normal interpreter termination.
+
+Note: the functions registered via this module are not called when the program is killed by a
+signal, when a Python fatal internal error is detected, or when
+\code{os._exit()} is called.
+
+This is an alternate interface to the functionality provided by the
+\code{sys.exitfunc} variable.
+\withsubitem{(in sys)}{\ttindex{exitfunc}}
+
+\begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}}
+Register \var{func} as a function to be executed at termination. Any
+optional arguments that are to be passed to \var{func} must be passed
+as arguments to \function{register()}.
+
+At normal program termination (for instance, if
+\function{sys.exit()} is called or the main module's execution
+completes), all functions registered are called in last in, first out
+order. The assumption is that lower level modules will normally be
+imported before higher level modules and thus must be cleaned up
+later.
+\end{funcdesc}
+
+
+\subsection{\module{atexit} Example \label{atexit-example}}
+
+The following simple example demonstrates how a module can initialize
+a counter from a file when it is imported and save the counter's
+updated value automatically when the program terminates without
+relying on the application making an explicit call into this module at
+termination.
+
+\begin{verbatim}
+try:
+ _count = int(open("/tmp/counter").read())
+except IOError:
+ _count = 0
+
+def incrcounter(n):
+ global _count
+ _count = _count + n
+
+def savecounter():
+ open("/tmp/counter", "w").write("%d" % _count)
+
+import atexit
+atexit.register(savecounter)
+\end{verbatim}
+
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index 01887da..9b4f906 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -127,7 +127,9 @@ way to exit a program when an error occurs.
This value is not actually defined by the module, but can be set by
the user (or by a program) to specify a clean-up action at program
exit. When set, it should be a parameterless function. This function
- will be called when the interpreter exits. Note: the exit function
+ will be called when the interpreter exits. Only one function may be
+ installed in this way; to allow multiple functions which will be called
+ at termination, use the \refmodule{atexit} module. Note: the exit function
is not called when the program is killed by a signal, when a Python
fatal internal error is detected, or when \code{os._exit()} is called.
\end{datadesc}