Tcl_Exit(), Tcl_Finalize(), Tcl_CreateExitHandler(), Tcl_DeleteExitHandler(), Tcl_ExitThread(), Tcl_FinalizeThread(), Tcl_CreateThreadExitHandler(), Tcl_DeleteThreadExitHandler()

end the application or thread (and invoke exit handlers) 

Tcl Library Procedures

SYNOPSIS

#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)

ARGUMENTS

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.

ClientData clientData (in) 

Arbitrary one-word value to pass to proc.

DESCRIPTION

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.

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. On some systems Tcl is automatically notified when it is being unloaded, and it calls Tcl_Finalize() internally; on these systems it not necessary for the caller to explicitly call Tcl_Finalize(). However, to ensure portability, your code should always invoke Tcl_Finalize() when Tcl is being unloaded, to ensure that the code will work on all platforms. 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.

PORTABILITY

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

PTC MKS Toolkit 10.4 Documentation Build 39.