Seth Woolley's Man Viewer

Tcl_CreateThreadExitHandler(3) - Tcl_CreateExitHandler, Tcl_CreateThreadExitHandler, Tcl_DeleteExitHandler, Tcl_DeleteThreadExitHandler, Tcl_Exit, Tcl_ExitThread, Tcl_Finalize, Tcl_FinalizeThread - end the application or thread (and invoke exit handlers) - man 3 Tcl_CreateThreadExitHandler

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

Tcl_Exit(3)                 Tcl Library Procedures                 Tcl_Exit(3)



______________________________________________________________________________

NAME
       Tcl_Exit,  Tcl_Finalize,  Tcl_CreateExitHandler, Tcl_DeleteExitHandler,
       Tcl_ExitThread,    Tcl_FinalizeThread,     Tcl_CreateThreadExitHandler,
       Tcl_DeleteThreadExitHandler - end the application or thread (and invoke
       exit(3,n,1 builtins) handlers)

SYNOPSIS
       #include <tcl.h>

       Tcl_Exit(status)

       Tcl_Finalize()

       Tcl_CreateExitHandler(proc(5,n), clientData)

       Tcl_DeleteExitHandler(proc(5,n), clientData)

       Tcl_ExitThread(status)

       Tcl_FinalizeThread()

       Tcl_CreateThreadExitHandler(proc(5,n), clientData)

       Tcl_DeleteThreadExitHandler(proc(5,n), clientData)

ARGUMENTS
       int            status       (in(1,8))      Provides  information  about  why
                                             the application or thread exited.
                                             Exact meaning  may  be  platform-
                                             specific.  0 usually means a nor-
                                             mal exit(3,n,1 builtins), any nonzero value  usu-
                                             ally    means   that   an   error(8,n)
                                             occurred.

       Tcl_ExitProc   *proc(5,n)        (in(1,8))      Procedure to invoke before  exit-
                                             ing application.

       ClientData     clientData   (in(1,8))      Arbitrary  one-word value to pass
                                             to proc(5,n).
_________________________________________________________________


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(3,n,1 builtins) from this process.
       This  procedure is invoked by the exit(3,n,1 builtins) command, and can be invoked any-
       place else to terminate the application.  No-one should ever invoke the
       exit(3,n,1 builtins)  system  procedure  directly;   always invoke Tcl_Exit instead, so
       that it can invoke exit(3,n,1 builtins) handlers.  Note that if(3,n) other code invokes exit(3,n,1 builtins)
       system  procedure directly, or otherwise causes the application to ter-
       minate without calling Tcl_Exit, the exit(3,n,1 builtins) handlers  will  not  be  run.
       Tcl_Exit internally invokes the exit(3,n,1 builtins) system call, thus it never returns
       control to its caller.

       Tcl_Finalize is similar to Tcl_Exit except that it does not  exit(3,n,1 builtins)  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(1,8)  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  plat-
       forms. Tcl_Finalize can be safely called more than once.

       Tcl_ExitThread  is used to terminate the current thread and invoke per- |
       thread exit(3,n,1 builtins) handlers.  This finalization is done by Tcl_FinalizeThread, |
       which  you  can  call if(3,n) you just want to clean up per-thread state and |
       invoke the thread exit(3,n,1 builtins) handlers.  Tcl_Finalize calls Tcl_FinalizeThread |
       for the current thread automatically.

       Tcl_CreateExitHandler  arranges  for proc(5,n) to be invoked by Tcl_Finalize
       and Tcl_Exit.  Tcl_CreateThreadExitHandler  arranges  for  proc(5,n)  to  be
       invoked by Tcl_FinalizeThread and Tcl_ExitThread.  This provides a hook
       for cleanup operations such as flushing buffers and freeing global mem-
       ory.  Proc should match the type Tcl_ExitProc:
              typedef void Tcl_ExitProc(ClientData clientData);
       The  clientData  parameter to proc(5,n) 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(1,8) proc(5,n).

       Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called  to
       delete a previously-created exit(3,n,1 builtins) handler.  It removes the handler indi-
       cated by proc(5,n) and clientData so that no call to proc(5,n) will be made.   If
       no  such handler exists then Tcl_DeleteExitHandler or Tcl_DeleteThread-
       ExitHandler does nothing.


       Tcl_Finalize and Tcl_Exit execute  all  registered  exit(3,n,1 builtins)  handlers,  in(1,8) |
       reverse  order  from  the  order  in(1,8)  which they were registered.  This |
       matches the natural order in(1,8) which extensions are loaded and  unloaded; |
       if(3,n) extension A loads extension B, it usually unloads B before it itself |
       is unloaded.  If extension A registers its exit(3,n,1 builtins) handlers before loading |
       extension B, this ensures that any exit(3,n,1 builtins) handlers for B will be executed |
       before the exit(3,n,1 builtins) handlers for A.                                         |

       Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the  thread  exit(3,n,1 builtins) |
       handlers  after the process-wide exit(3,n,1 builtins) handlers.  This is because thread |
       finalization shuts down the I/O channel system, so any attempt  at  I/O |
       by the global exit(3,n,1 builtins) handlers will vanish into the bitbucket.


KEYWORDS
       callback,  cleanup,  dynamic loading, end application, exit(3,n,1 builtins), unloading,
       thread



Tcl                                   8.1                          Tcl_Exit(3)

References for this manual (incoming links)