home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / biblioteki / c_library / rtlibrary / readme < prev    next >
Text File  |  1977-12-31  |  4KB  |  97 lines
  1. short: A kind of "resource tracking" makes cleanup easier.
  2. author: Tomi Ollila <too@cs.hut.fi>
  3.  
  4. This library is public domain. Use it any way you want. I do :)
  5. No warranty of any kind is given.
  6.  
  7. Rt library provides a way to "remember" what resources has been allocated 
  8. for the task a program is doing. Then, at the end of program execution, one
  9. `delete' -call will go through a stack of allocated stuff and call their
  10. corresponding deallocation functions.
  11.  
  12. The initial and final procedures one must do are quite simple:
  13.  
  14. First, create an rt memory space. Currently this space is statically bound
  15. to the value programmer gives. Programmer must know/quess a value high
  16. enough for all stuff that rt must remember: This is done the following way:
  17.  
  18.     struct RT * rt;
  19.  
  20.     unless (rt = rt_Create(100)) /* #define unless(x) if (!(x)) */
  21.        return 20;
  22.  
  23. This allocates memory for 100 items that rt can remember.
  24.  
  25. ...Now you can for example do the following thing (and then forget the
  26. thing alltogether):
  27.  
  28.     void closeLib(struct Library * base) { CloseLibrary(base); }
  29. ...
  30.  
  31.     unless (DOSBase = (struct DosLibrary *)OpenLibrary("dos.library", 37))
  32.        return 20;
  33.  
  34.     rt_Add(rt, closeLib, DOSBase);
  35.  
  36. but all this can be done easier by using the provided rt_CloseLib -function:
  37.  
  38.     unless (rt_CloseLib(rt, &DOSBase, "dos.library", 37))
  39.        return 20;
  40.  
  41.  
  42. As you see, the rt -system takes a pointer to deallocation function and a
  43. data pointer to be given as an argument to that function. At the end of
  44. program execution, the following call will do all these deallocation
  45. function calls in reverse order they were installed.
  46.  
  47. rt_Delete(rt);
  48.  
  49.  
  50. The library in current state provides the following functions:
  51.  
  52. /* rt.c */
  53. struct RT * rt_Create(int size); /* creates an rt instance */
  54. struct RTNode * rt_Add(struct RT * rt, void * func, void * data);
  55. struct RTNode * rt_Delete(struct RT * rt);
  56.  
  57. /* rt_remnode.c -- the function below deletes one node */
  58. void rt_RemNode(struct RT * rt, struct RTNode * node);
  59.  
  60. /* rt_remdata.c -- the function below deletes one node searched by data ptr */
  61. void rt_Remdata(struct RT * rt, void * data);
  62.  
  63. /* rt_remsome.c -- function deletes multiple entries ... */
  64. void rt_Remdata(struct RT * rt, void * ptr, ULONG flags);
  65.  
  66. /* rt_exec/rt_openlib.c -- void * as libptr reduces compiler warnings */
  67. struct RTNode * rt_OpenLib(struct RT * rt, void * libptr, 
  68.                 char * name, int version); */
  69.  
  70. /* rt_exec/rt_allocmem.c -- void * as memptr reduces compiler warnings */
  71. struct RTNode * rt_AllocMem(struct RT * rt, void * memptr,
  72.                 ULONG size, ULONG flags);
  73.  
  74. /* rt_dos/rt_open.c */
  75. struct RTNode * rt_Open(struct RT * rt, BPTR * file, char * name, int mode);
  76.  
  77.  
  78. See the test program in test directory of this archive. It demonstrates
  79. the way those rt_Rem* -functions work (1384 bytes long and it uses almost
  80. all the functions provided in the library). 
  81.  
  82. If you want to add your own rt functions to this library, please follow the
  83. convention I've been using in rt_exec/ and rt_dos/ directories. I will gladly
  84. add all your "wrappers" you want to be included in this public distribution
  85. of this library.
  86.  
  87. All sources and this library is compiled w/ gcc only, since it was so easy
  88. to use gcc cross compiler at sun sparcstation while developing this library
  89. (21" monitor, X and Emacs19 rules).
  90.  
  91. Well, This documentation should give you a start of trying and using this
  92. library. Please send me comments about the usability and everything you
  93. could think about this piece of work to the address too@cs.hut.fi.
  94.  
  95. Tomi
  96.  
  97.