home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 497a.lha / ComSMUS_v2.2 / src / CLEANUP.README < prev    next >
Encoding:
Text File  |  1991-04-07  |  4.4 KB  |  161 lines
  1.  
  2.  
  3. README file for the Hackercorp Amiga cleanup routines
  4. -----------------------------------------------------
  5.  
  6. The cleanup routines are placed in the public domain by
  7. Hackercorp in the hope that they will be of use to other
  8. Amiga developers.
  9.  
  10. They may be included in a commercial product without
  11. license from or royalty to Hackercorp.  Credit need
  12. not be given to Hackercorp in documentation, title
  13. screen, etc, although it is always appreciated.
  14.  
  15. If you pass along the source, we ask that you retain
  16. our names as the developers of the tool.
  17.  
  18. All correspondence is welcome.  If you fix a bug, make
  19. an improvement, etc, try to pass it back to us.
  20.  
  21.  
  22. The Cleanup Routines
  23. --------------------
  24.  
  25. Everyone who has ever programmed the Amiga in C has had to deal with the
  26. fact that the Amiga doesn't do resource tracking.  Consequently, when
  27. your program exits, it must free all its locks, close all its libraries,
  28. close all its screens, free all its memory, etc, etc, etc.
  29.  
  30. This job can be quite daunting, especially when a failure to allocate
  31. something can occur at any point in the program's startup or execution.
  32.  
  33. We at Hackercorp have evolved some techniques and written some code
  34. to help ease this burden and we are sharing them now, to wit:
  35.  
  36.     o add_cleanup() routine that lets you queue up functions to be
  37.       executed at exit time
  38.  
  39.     o cleanup() which is called at exit time to execute your cleanup
  40.       routines
  41.  
  42.  
  43.     o Initialize your pointers to NULL and only deallocate in your
  44.       cleanup routines if the pointer is non-null.
  45.  
  46.  
  47.  
  48. Example
  49. -------
  50.  
  51. Consider a large program.  You may find it reasonable to open and close
  52. all of your libraries in a file called libraries.c.  There is an init
  53. routine to be called from main() or somewhere else in your startup.
  54. That init routine, when executed, calls add_cleanup to queue the cleanup
  55. routine to be executed at exit time.
  56.  
  57. An example from one of my programs:
  58.  
  59. --- libraries.c ------------------------
  60.  
  61. #include <functions.h>
  62. #include <exec/types.h>
  63. #include <exec/devices.h>
  64. #include <intuition/intuition.h>
  65. #include <ctype.h>
  66. #include <midi/midi.h>
  67.  
  68. struct IntuitionBase *IntuitionBase = NULL;
  69. struct MidiBase *MidiBase = NULL;
  70.  
  71. trash_libs()
  72. {
  73.     if (IntuitionBase) 
  74.         CloseLibrary(IntuitionBase);
  75.  
  76.     if (MidiBase)
  77.         CloseLibrary(MidiBase);
  78. }
  79.  
  80. init_libs()
  81. {
  82.     add_cleanup(trash_libs);
  83.  
  84.     if (!(IntuitionBase = (struct IntuitionBase *)OpenLibrary("intuition.library",0L)))
  85.         panic("Can't open intuition.library");
  86.  
  87.     MidiBase = (struct MidiBase *)OpenLibrary(MIDINAME,MIDIVERSION);
  88.  
  89.     if (MidiBase == NULL)
  90.         panic("Can't open midi.library");
  91. }
  92.  
  93. --------------------------------------
  94.  
  95.  
  96. You then call init_libs() from your main prior to using the libraries.
  97. When you exit, be sure and call cleanup().  If you do so, cleanup will
  98. execute your cleanup routines in the reverse order they were queued,
  99. which is the reasonable way to do it.  This way, you don't have to
  100. have icky all-encompassing cleanup routines.
  101.  
  102. The Manx I/O routines abort the program if they detect a control-C when
  103. they're called. There's a routine called _abort() that gets called by
  104. the control-C code, so we need to replace it with our own that calls
  105. cleanup.  For a CLI program, this could be:
  106.  
  107. _abort()
  108. {
  109.     cleanup();
  110.     printf("^C abort\n");
  111.     exit(1);
  112. }
  113.  
  114. Workbench may want to do fancier things.
  115.  
  116. I like to have a routine called panic() that takes a string for the
  117. panic reason and just lets you get the heck out with the minimum
  118. effort.  Note the calls to panic in the init_libs routine above.
  119. It's a bit drastic, but appropriate when appropriate.
  120.  
  121. A panic routine for a CLI program might be:
  122.  
  123. panic(s)
  124. char *s;
  125. {
  126.     fprintf(stderr,"panic: %s\n",s);
  127.     fflush(stdout);
  128.     fflush(stderr);
  129.     cleanup();
  130.     exit(1);
  131. }
  132.  
  133. The panic function provide in the cleanup.c file is a little slicker,
  134. it can detect a "double panic."  This is a condition that could occur
  135. if one of your cleanup routines ended up doing a panic() during a
  136. panic().
  137.  
  138. There's a file called displayrequest.c included herein that takes a
  139. string and puts up a requester.  Workbench-launchable programs, rather
  140. than printf'ing the error, might consider doing a:
  141.  
  142.     DisplayRequest(s,"PANIC","PANIC");
  143.  
  144. Note that intuition.library must be open for this to work.
  145.  
  146.  
  147.  
  148. Regards,
  149.  
  150. Karl Lehenbauer
  151. Peter da Silva
  152.  
  153. Hackercorp
  154. 3918 Panorama
  155. Missouri City, TX  77459
  156. 713-438-4964 voice
  157. 713-438-5018 data
  158.  
  159. Internet/BITNET: karl@sugar.hackercorp.com, peter@sugar.hackercorp.com
  160. USENET: uunet!sugar!karl, uunet!sugar!peter
  161.