home *** CD-ROM | disk | FTP | other *** search
/ MacFormat España 21 / macformat_21.iso / Shareware / Programación / VideoToolbox / VideoToolboxSources / AtExitToShell.c < prev    next >
Encoding:
Text File  |  1996-08-05  |  5.7 KB  |  138 lines  |  [TEXT/CWIE]
  1. /*
  2. AtExitToShell.c
  3.  
  4.     void YourFunction(void);
  5.  
  6.     error=AtExitToShell(YourFunction);
  7.  
  8. AtExitToShell(YourFunction) requests that your function be called when the
  9. application quits, i.e. calls the ExitToShell trap, which tells the MacOS that
  10. it's done. Your function must have no arguments and no return value.
  11.  
  12. (MATLAB: If you compile this file as a MEX resource, to be called from MATLAB, 
  13. then your call to AtExitToShell is a request that your function be called when 
  14. the MEX resource is flushed from memory.)
  15.  
  16. Many VideoToolbox routines set up interrupt service routines that must be killed
  17. before the program goes away. We want to kill these whether we quit via exit(),
  18. abort(), or the ExitToShell trap is invoked directly, e.g. if user types "ES"
  19. in MacsBug. The only way to be sure of killing something before the application
  20. goes away is to attach its killer, by patching, to the ExitToShell trap. That's
  21. what's done here.
  22.  
  23. AtExitToShell() is closely modeled on the ANSI function atexit(). I wrote it to
  24. overcome the restrictive implementation of atexit() and _atexit() in CodeWarrior:
  25. they only invoke your functions if the ANSI function exit() is called, NOT if
  26. you call abort(), or the user types "ES" in MacsBug. I think that AtExitToShell
  27. is equivalent to the non-ANSI _atexit() routine provided by the Symantec THINK C
  28. environment.
  29.  
  30. The registration list (of user functions) is last-in, first-out. When you
  31. eventually quit, your functions will be called in reverse of the order in which
  32. you registered them. No checking is made for duplication: the same function may
  33. be registed multiple times, and will be called multiple times.
  34.  
  35. CAUTION: your application's runtime environment (e.g. stdio) will normally have
  36. shut itself down by the time it calls ExitToShell(), so a function scheduled for 
  37. that time should not assume the availability of such services (e.g. printf). 
  38. There's no restriction on the use of MacOS services.
  39.  
  40. MATLAB: the Standard C atexit() and THINK C _atexit() routines should not be 
  41. used in MATLAB code resources, because they aren't designed to handle the
  42. situation of code that may be flushed any time MATLAB executes "clear mex" or
  43. "clear all", at a time unrelated to exiting of the MATLAB application itself. 
  44. Instead, MATLAB provides mexAtExit(), which allows you to register one callback 
  45. per MEX file, which is called when the MEX file is flushed. (The problem with using
  46. mexAtExit, is that it's hard for any particular subroutine to know whether somebody
  47. else has already used up the single available slot in the call-back table.)
  48. In order to make your C subroutines as portable and autonomous as possible, you may
  49. prefer to use this AtExitToShell() which allows you to register lots of callback 
  50. routines, and registers itself, once, with mexAtExit. 
  51.  
  52. CAUTION: Since MATLAB registers only one function per MEX it is important that 
  53. you consistently adopt one strategy. Either make lots of calls to AtExitToShell
  54. (and NONE to mexAtExit), or just one call to mexAtExit. If you call both AtExitToShell
  55. and mexAtExit then one will displace the other in MATLAB's one-entry table.
  56.  
  57. The code to patch ExitToShell is based on examples that appeared in UseNet
  58. csmp-digest-v3-046 by Kevin Bell (kbell@cs.utexas.edu) and Bill Hofmann
  59. (wdh@netcom.com) in response to a query by Steve Coy (stevec@jolt.mpx.com.au)
  60.  
  61. HISTORY:
  62. 10/27/94 dgp wrote the ExitToShell patch, based on code from UseNet csmp-digest.
  63. 6/17/95 dgp wrote AtExitToShell.c
  64. 7/1/95 dgp made compatible with pre-universal apple headers. 
  65.     Disable if MATLAB is true. Added comments about MATLAB. 
  66. 7/17/95 dgp made compatible with pre-universal headers
  67. 4/19/96 dgp call mexAtExit(). I know this is ok for PPC, but may not work for 68k.
  68. 6/10/96 dgp fixed initialization error when MATLAB is true.
  69. 6/10/96 dgp added a couple paragraphs explaining its use in MATLAB MEX files.
  70. 6/11/96 dgp In response to concerns raised by David Brainard, I added text above
  71.         warning about the danger of calling BOTH AtExitToShell and mexAtExit, and
  72.         I made the A5 stuff conditional on !MATLAB.
  73. 8/5/96    dgp #undef mexAtExit to make sure we call the real McCoy.
  74. */
  75. #include "VideoToolbox.h"
  76. #ifndef __TRAPS__
  77.     #include <Traps.h>    // _ExitToShell
  78. #endif
  79. #include <SegLoad.h>    // ExitToShell()
  80. #if UNIVERSAL_HEADERS
  81.     typedef UniversalProcPtr TrapAddressType;
  82. #else
  83.     #define UniversalProcPtr ProcPtr
  84.     #define NewRoutineDescriptor(a,b,c) a
  85.     typedef long TrapAddressType;
  86. #endif
  87. static pascal void MyExitToShell(void);
  88. #define FUNCTIONS 35
  89. static UniversalProcPtr oldExitToShellTrapAddress=NULL;    // save address of real ExitToShell trap.
  90. static void (*userFunction[FUNCTIONS])(void);    // table of user functions to be called at exit.
  91.  
  92. int AtExitToShell(void (*userFunctionPtr)(void))
  93. {
  94.     #if !MATLAB
  95.         UniversalProcPtr myExitToShellUPP;
  96.     #endif
  97.     int i;
  98.     static Boolean firstTime=1;
  99.  
  100.     if(firstTime){
  101.         #if !MATLAB
  102.             myExitToShellUPP=NewRoutineDescriptor((ProcPtr)MyExitToShell
  103.                 ,kPascalStackBased,GetCurrentISA());
  104.             oldExitToShellTrapAddress=(UniversalProcPtr)GetToolTrapAddress(_ExitToShell);
  105.             SetToolTrapAddress((TrapAddressType)myExitToShellUPP,_ExitToShell);
  106.         #else
  107.             // Ask MATLAB to call MyExitToShell just before disposing of our MEX resource.
  108.             #undef mexAtExit
  109.             mexAtExit((void *)MyExitToShell);
  110.         #endif
  111.         for(i=0;i<FUNCTIONS;i++)userFunction[i]=NULL;
  112.         firstTime=0;
  113.     }
  114.     for(i=0;i<FUNCTIONS;i++)if(userFunction[i]==NULL){
  115.         userFunction[i]=userFunctionPtr;
  116.         return 0;    // success
  117.     }
  118.     return 1;        // failure: the table's already full
  119. }
  120.  
  121. static pascal void MyExitToShell(void)
  122. {
  123.     int i;
  124.     
  125.     #if !MATLAB
  126.         SetCurrentA5();
  127.         SetToolTrapAddress((TrapAddressType)oldExitToShellTrapAddress,_ExitToShell);
  128.     #endif
  129.  
  130.     for(i=FUNCTIONS-1;i>=0;i--)if(userFunction[i]!=NULL){
  131.         (*userFunction[i])();
  132.     }
  133.  
  134.     #if !MATLAB
  135.         ExitToShell();
  136.     #endif
  137. }
  138.