home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / misc / gold03.lzh / GF_003 / LOWMEM / README < prev    next >
Text File  |  1991-04-28  |  14KB  |  305 lines
  1.  
  2.             ASDG Low Memory Server Documentation
  3.  
  4.             Copyright 1987 By  ASDG Incorporated
  5.         All Rights, Except Those Granted Herein, Reserved
  6.  
  7. 1. Terms Of Distribution
  8. -----------------------------------------------------------------------------
  9.  
  10. Permission for the non-commercial distribution of the ASDG Low Memory Server 
  11. is hereby granted. Non-commercial distribution is defined as distribution by
  12. user groups, individuals  not for  profit, public service public domain disk 
  13. distributors (ie: my friend Fred Fish). 
  14.  
  15.     [Editor note:  While putting together the third disk
  16.     in the "GoldFish" series, I contacted Perry directly
  17.     and was given explicit permission to place this material
  18.     on the disk set to be distributed by Commodore for
  19.     promotional purposes.  This permission should not be
  20.     construed as invalidating any of the other provisions
  21.     herein.   Fred Fish, 28-Jul-87]
  22.  
  23. Any manufacturer of hardware  or  software is specifically enjoined from the
  24. public distribution of  any  part  of the Low Memory Server unless licensing
  25. by ASDG is received.
  26.  
  27. The Low Memory Server is specifically NOT in the public domain. 
  28.  
  29. 2. Commercial Licensing
  30. -----------------------------------------------------------------------------
  31.  
  32. ASDG encourages the commercial use of  the  Low  Memory Server provided that
  33. following provisions are affirmed  and  agreed upon by ASDG and the prospec-
  34. tive licensee.
  35.  
  36. (a) The licensee agrees to credit ASDG  Incorporated for the use of the Low
  37.     Memory Server in some reasonable visible fashion in the licensee's pro-
  38.     duct documentation,
  39. (b) The licensee agrees to furnish ASDG with a finished product as it would
  40.     be purchased by the consumer.
  41.  
  42. Should ASDG find it  necessary, a  licensing fee of no more than $50 (U.S.)
  43. may required in addition to the above. This fee is  a  one time expense and
  44. shall be used to defray the cost of providing the license agreement.
  45.  
  46. 3. What Is The ASDG Low Memory Server
  47. -----------------------------------------------------------------------------
  48.  
  49. The ASDG Low Memory Server is a compact (900 bytes) shared library which al-
  50. lows arbitrary processes to  register their desire to be notified of impend-
  51. ing memory shartages.
  52.  
  53. The purpose of the LMS is to allow for the easy notification of applications
  54. that they should attempt to clean up or reduce their memory memory consumpt-
  55. ion or face a complete absence of available memory.
  56.  
  57. For example, a graphics or sound editor may elect to be notified that memory
  58. is becoming scare  and  if  so  notified  will deallocate space used to hold
  59. sounds or graphics  no longer  in current use by the user but which were re-
  60. tained in ram as a performance  boost in the event that the user would elect
  61. to reuse the data at a later time.
  62.  
  63. The ASDG LMS provides a reliable low memory  notification service which will
  64. be tripped upon any failure  of  an AllocMem system call. Note: the ASDG LMS
  65. uses operating system mechanics  already  present in 1.2 - it does not alter
  66. or modify any system code - anywhere. Specifically, AllocMem is NOT touched.
  67.  
  68. Notification is performed  via the natural interprocess communications prim-
  69. itive available on the Amiga, the message.
  70.  
  71. Support for the ASDG LMS is intended to be coded into your application.  The
  72. remainder of this document is an explanation of how this is done.
  73.  
  74. 4. As A Programmer, What Do You Agree To Do?
  75. -----------------------------------------------------------------------------
  76.  
  77. You agree (by writing your code correctly) to the following things:
  78.  
  79. (a) You  will allocate and  initialize a message port to be used by the ASDG
  80.     LMS to notify you.
  81. (b) You will allocate  and initialize  a LowMemMsg  structure which  will be
  82.     used BY the ASDG LMS to notify you.
  83. (c) To be effective, you  agree  to  monitor your LMS message port in all of
  84.     your calls to Wait.
  85. (d) You agree to call DeRegLowMemReq when exiting, prior to closing the ASDG
  86.     LMS library.
  87. (e) You agree to close the ASDG LMS library when done.
  88. (f) You agree to reinitialize your LowMemMsg each time the ASDG LMS notifies
  89.     you of memory shortages.
  90. (g) You agree  to examine the return code from RegLowMemReq. This routine is
  91.     your interface  to the Low Memory Server registration list. It will tell
  92.     you if the message  port  name you  supplied has  already  been  used by
  93.     someone else.
  94.  
  95. If  you  fail  to do these things,  there isn't much point in using the ASDG
  96. LMS.
  97.  
  98. 5. The LMS Message Port
  99. -----------------------------------------------------------------------------
  100.  
  101. You must allocate and initialize  a  message port to which the LMS will send
  102. you its low memory notification message. You  may  do this in the usual way.
  103. However, you must be prepared to delete this message port and re-allocate it
  104. as many times as is needed to get a unique message port name.
  105.  
  106. After defining the message  port (with  a  name you hope will be unique) and
  107. defining a LowMemMsg  (see  later)  you will register your message port name
  108. with the ASDG  LMS  by  calling  RegLowMemReq. This call may return an error
  109. value indicating that the message port name  is  not unique. Your request to
  110. register with the LMS has been denied  and you must delete your message port
  111. and redefine one with another name (and  loop to the call to RegLowMemReq a-
  112. gain).
  113.  
  114. This ensures that only one port with any given  name will be registered with
  115. the LMS.
  116.  
  117. 6. The LowMemMsg
  118. -----------------------------------------------------------------------------
  119.  
  120. YOU have to  allocate  a  LowMemMsg structure. This will be the message that
  121. LMS uses to notify you of a low memory condition.
  122.  
  123. You define it rather than the LMS since if  the LMS  needs  to  get in touch
  124. with you, it is because there is a low  memory situation present. Hardly the
  125. time to go allocating message storage.
  126.  
  127. The LowMemMsg structure is defined in low-mem.h as is as follows:
  128.  
  129.     struct LowMemMsg {
  130.         struct Message lm_msg;
  131.         long lm_flag;
  132.     };
  133.  
  134. This is simply a  usual message structure with a long word flag tagged on the
  135. end. The only  initialization YOU have to do is to set the lm_flag to a spec-
  136. ific value, LM_CONDITION_ACKNOWLEDGED. The  LMS will  initialize the  rest of
  137. the message for you.
  138.  
  139. Setting lm_flag  to LM_CONDITION_ACKNOWLEDGED is  cruicial  to your receiving
  140. messages from the LMS. Immediately  prior  to  sending  you a message the LMS
  141. will (after verifying  that  your registered message port exists) interrogate
  142. your lm_flag. If it is not set to LM_CONDITION_ACKNOWLEDGED then the LMS will
  143. not send you the message.
  144.  
  145. You are specifically NOT to Reply  to  the  message you receive from the LMS.
  146. The LMS is being run directly from  a failing AllocMem call by someone else's
  147. program. To prevent  the possibility  of a  program NOT replying to the LMS's
  148. message (and thus deadlocking the system) I use the LM_CONDITION_ACKNOWLEDGED
  149. value in lm_flag to signify that your process has acknolwedged the receipt of
  150. its previous low memory message.
  151.  
  152. Repeat - DO NOT REPLY TO THE LOW MEMORY MESSAGE - SET lm_flag INSTEAD! Here's
  153. the definition of LM_CONDITION_ACKNOWLEDGED:
  154.  
  155. #define    LM_CONDITION_ACKNOWLEDGED    (('A'<<24)|('S'<<16)|('D'<<8)|'G')
  156.  
  157. 7. Requesting Registration
  158. -----------------------------------------------------------------------------
  159.  
  160. After defining your message port to be  used  by the LMS to notify you of a
  161. low memory situation and defining a LowMemMsg structure,  you register your
  162. message port and message structure with the ASDG LMS by calling the library
  163. routine ``RegLowMemReq''. 
  164.  
  165. The call takes the following form:
  166.  
  167.     Result = RegLowMemReq(PortName , PtrToLowMemMsg);
  168.       d0                     a0             a1
  169.  
  170. The call will return 0 if all went  well.  This  return  indicates that you
  171. will be receiving low memory warnings through the specified port. If,  how-
  172. ever you do not receive a  0  result  then  something went astray with your
  173. registration request. 
  174.  
  175. Two error results are defined. These are:
  176.  
  177. #define    LM_BADNAME    -1    /* duplication of port name */
  178. #define    LM_NOMEM    -2    /* memory allocation failed */
  179.  
  180. If you receive LM_BADNAME then the ASDG LMS is telling you that someone has
  181. previously registered the  same port  name as  you have  just tried. Simply
  182. change the name and resubmit the request (taking into account the fact that
  183. you might have already allocated a port with the invalid name).
  184.  
  185. The following flow chart indicates a reasonable way to choose a port name:
  186.  
  187.                 Forbid()
  188.                    |
  189.                    |
  190.                      Choose A Name <----------\-----\
  191.                        |                  |     |
  192.                    |                  |     |
  193.                         FindPort              |     |
  194.                    |                  |     |
  195.                    |            (yes) |     |
  196.                  Port Already Defined?--------/     |
  197.                        |                        |
  198.                    | (no)                   |
  199.                    |                        |
  200.                  RegLowMemReq                   |
  201.                        |                        |
  202.                    |            (yes)       |
  203.           (Note 1)---------->Fail?----------------------/
  204.                    |
  205.                    | (no)
  206.                    |
  207.                        CreatePort
  208.                    |
  209.                    |
  210.                 Permit
  211.                    |
  212.                    v
  213.  
  214. Note 1: This can happen since someone may  have DeletePort'ed  their message
  215. port  but  NOT  canceled   their   reservation   with  the  LMS  by  calling 
  216. DeRegLowMemReq.
  217.  
  218. 8. Requesting DeRegistration
  219. -----------------------------------------------------------------------------
  220.  
  221. As part of your program's  exit process  you should cancel your registration
  222. with the LMS. This is  done by calling DeRegLowMemReq with the LMS port name
  223. as the only argument.  If you  do not  call this  routine before exiting AND
  224. some other process still has the LMS  library  open, the memory that the LMS
  225. library allocated to store your registration will not be freed. 
  226.  
  227. However, when the  last  process  that has the LMS library open finally does
  228. close it, all remaining  nodes  (from people who didn't call DeRegLowMemReq)
  229. will be expunged along with the rest of the library.
  230.  
  231. Summary of call:
  232.  
  233.     (void) DeRegLowMemReq(PortName);
  234.                              a0
  235.  
  236. 9. Closing The LMS Library
  237. -----------------------------------------------------------------------------
  238.  
  239. It is absolutely  critical that  your close  the LMS  library before exiting
  240. your program. If you don't,  the  library's open count can never again go to
  241. zero causing  the  library to  be unable  to expunge itself from memory when
  242. otherwise no longer  needed. While the LMS is very compact this is still not
  243. a wise thing to do.
  244.  
  245. The LMS library is closed in the following way:
  246.  
  247.     CloseLibrary(LowMemBase);
  248.  
  249. Note that the long integer LowMemBase must be declared somewhere in your ap-
  250. plication using the above spelling.
  251.  
  252. 10. The lm_flag Again...
  253. -----------------------------------------------------------------------------
  254.  
  255. This chapter is here JUST to remind you that the LMS will look for a specif-
  256. if value in your lm_flag LowMemMsg field.  If  lm_flag is not LM_CONDITION_-
  257. ACKNOWLEDGED, then the LMS will not send you any more messages.
  258.  
  259. 11. Hints For Using The ASDG LMS Effectively
  260. -----------------------------------------------------------------------------
  261.  
  262. If AllocMem detects that it is going to fail due to lack of memory, it will
  263. run the list  of libraries  calling each library's expunge routine in turn.
  264. The LMS upon having its expunge  routine tickled  will run through its list
  265. of registrations sending off  messages  to  each  registers message port in
  266. turn (the last thing you want here is to have LMS wait for a reply so it is
  267. written  specifically NOT  to - so don't reply to any messages that the LMS
  268. may send you).
  269.  
  270. Some calls to AllocMem fail  even  when there's plenty of memory available.
  271. For example, a  request   to  AllocMem  for 2 megabytes of memory on a 512K
  272. Amiga will certainly fail even though there might be 400K still available.
  273.  
  274. To really use the LMS  effectively,  the first thing your program should do
  275. is to actually interrogate the  amount of memory available on the system by
  276. calling AvailMem. Thus, your program can tell the difference between a real
  277. memory emergancy and an AllocMem whose goals were unrealistic.
  278.  
  279. 12. About The ASDG LMS
  280. -----------------------------------------------------------------------------
  281.  
  282. The ASDG Low Memory Server was written completely in Manx Assembly Language
  283. by Perry S. Kivolowitz, president of ASDG Incorporated. The LMS was written
  284. as part of the development  of  ASDG's  update to Facc, FaccII. FaccII is a
  285. floppy accelerator  providing performance from floppy disk far in excess of
  286. current hard disks (with some limitations of course).
  287.  
  288. FaccII will use the  LMS  to  determine  when it should begin taking memory
  289. conservation measures. 
  290.  
  291. While FaccII is   a  commercial product, we have decided to release the LMS
  292. for non-commercial distribution (and licensed commercial distribution)  be-
  293. we view the LMS as a useful generic tool which we feel the Amiga  community
  294. as a whole would benefit from and, of course, we felt that doing this would
  295. be in the best interest of ASDG (besides why have everyone  write their own
  296. and possibly have several of them running on the machine at once?)
  297.  
  298. We feel ASDG has contributed as much to the betterment of the Amiga commun-
  299. ity  as any other vendor or private  contributor. The  ASDG Recoverable Ram
  300. Disk, tutorials in Amazing Computing, and  now  the LMS are examples of our
  301. love and committment for  the  Amiga  personal computer and the Amiga using
  302. community. This is our small way of showing that, yes,  we put back in  and
  303. not just take out.
  304.  
  305.