Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler,
Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler,
Tcl_DeleteThreadExitHandler, Tcl_SetExitProc - end the application or thread
(and invoke exit handlers)
#include <tcl.h>
Tcl_Exit(status)
Tcl_Finalize()
Tcl_CreateExitHandler(proc, clientData)
Tcl_DeleteExitHandler(proc, clientData)
Tcl_ExitThread(status)
Tcl_FinalizeThread()
Tcl_CreateThreadExitHandler(proc, clientData)
Tcl_DeleteThreadExitHandler(proc, clientData)
Tcl_ExitProc *
Tcl_SetExitProc(proc)
- int status (in)
- Provides information about why the application or thread
exited. Exact meaning may be platform-specific. 0 usually means a normal
exit, any nonzero value usually means that an error occurred.
- Tcl_ExitProc *proc (in)
- Procedure to invoke before exiting application, or (for
Tcl_SetExitProc) NULL to uninstall the current application exit
procedure.
- ClientData clientData (in)
- Arbitrary one-word value to pass to proc.
The procedures described here provide a graceful mechanism to end the execution
of a
Tcl application. Exit handlers are invoked to cleanup the
application's state before ending the execution of
Tcl code.
Invoke
Tcl_Exit to end a
Tcl application and to exit from this
process. This procedure is invoked by the
exit command, and can be
invoked anyplace else to terminate the application. No-one should ever invoke
the
exit system procedure directly; always invoke
Tcl_Exit
instead, so that it can invoke exit handlers. Note that if other code invokes
exit system procedure directly, or otherwise causes the application to
terminate without calling
Tcl_Exit, the exit handlers will not be run.
Tcl_Exit internally invokes the
exit system call, thus it never
returns control to its caller. If an application exit handler has been
installed (see
Tcl_SetExitProc), that handler is invoked with an
argument consisting of the exit status (cast to ClientData); the application
exit handler should not return control to Tcl.
Tcl_Finalize is similar to
Tcl_Exit except that it does not exit
from the current process. It is useful for cleaning up when a process is
finished using
Tcl but wishes to continue executing, and when
Tcl is used in a dynamically loaded extension that is about to be
unloaded. Your code should always invoke
Tcl_Finalize when
Tcl
is being unloaded, to ensure proper cleanup.
Tcl_Finalize can be safely
called more than once.
Tcl_ExitThread is used to terminate the current thread and invoke
per-thread exit handlers. This finalization is done by
Tcl_FinalizeThread, which you can call if you just want to clean up
per-thread state and invoke the thread exit handlers.
Tcl_Finalize
calls
Tcl_FinalizeThread for the current thread automatically.
Tcl_CreateExitHandler arranges for
proc to be invoked by
Tcl_Finalize and
Tcl_Exit.
Tcl_CreateThreadExitHandler
arranges for
proc to be invoked by
Tcl_FinalizeThread and
Tcl_ExitThread. This provides a hook for cleanup operations such as
flushing buffers and freeing global memory.
Proc should match the type
Tcl_ExitProc:
typedef void Tcl_ExitProc(
ClientData clientData);
The
clientData parameter to
proc is a copy of the
clientData argument given to
Tcl_CreateExitHandler or
Tcl_CreateThreadExitHandler when the callback was created. Typically,
clientData points to a data structure containing application-specific
information about what to do in
proc.
Tcl_DeleteExitHandler and
Tcl_DeleteThreadExitHandler may be
called to delete a previously-created exit handler. It removes the handler
indicated by
proc and
clientData so that no call to
proc
will be made. If no such handler exists then
Tcl_DeleteExitHandler or
Tcl_DeleteThreadExitHandler does nothing.
Tcl_Finalize and
Tcl_Exit execute all registered exit handlers, in
reverse order from the order in which they were registered. This matches the
natural order in which extensions are loaded and unloaded; if extension
A loads extension
B, it usually unloads
B before it
itself is unloaded. If extension
A registers its exit handlers before
loading extension
B, this ensures that any exit handlers for
B
will be executed before the exit handlers for
A.
Tcl_Finalize and
Tcl_Exit call
Tcl_FinalizeThread and the
thread exit handlers
after the process-wide exit handlers. This is
because thread finalization shuts down the I/O channel system, so any attempt
at I/O by the global exit handlers will vanish into the bitbucket.
Tcl_SetExitProc installs an application exit handler, returning the
previously-installed application exit handler or NULL if no application
handler was installed. If an application exit handler is installed, that exit
handler takes over complete responsibility for finalization of Tcl's
subsystems via
Tcl_Finalize at an appropriate time. The argument passed
to
proc when it is invoked will be the exit status code (as passed to
Tcl_Exit) cast to a ClientData value.
exit(3tcl)
abort, callback, cleanup, dynamic loading, end application, exit, unloading,
thread