Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 092.lha / ASDG / LowMemoryServer / ReadMe < prev

Wrap

Text File | 1986-11-21 | 12.9 KB | 297 lines

ASDG Low Memory Server Documentation Copyright 1987 By ASDG Incorporated All Rights, Except Those Granted Herein, Reserved 1. Terms Of Distribution ----------------------------------------------------------------------------- Permission for the non-commercial distribution of the ASDG Low Memory Server is hereby granted. Non-commercial distribution is defined as distribution by user groups, individuals not for profit, public service public domain disk distributors (ie: my friend Fred Fish). Any manufacturer of hardware or software is specifically enjoined from the public distribution of any part of the Low Memory Server unless licensing by ASDG is received. The Low Memory Server is specifically NOT in the public domain. 2. Commercial Licensing ----------------------------------------------------------------------------- ASDG encourages the commercial use of the Low Memory Server provided that following provisions are affirmed and agreed upon by ASDG and the prospec- tive licensee. (a) The licensee agrees to credit ASDG Incorporated for the use of the Low Memory Server in some reasonable visible fashion in the licensee's pro- duct documentation, (b) The licensee agrees to furnish ASDG with a finished product as it would be purchased by the consumer. Should ASDG find it necessary, a licensing fee of no more than $50 (U.S.) may required in addition to the above. This fee is a one time expense and shall be used to defray the cost of providing the license agreement. 3. What Is The ASDG Low Memory Server ----------------------------------------------------------------------------- The ASDG Low Memory Server is a compact (900 bytes) shared library which al- lows arbitrary processes to register their desire to be notified of impend- ing memory shartages. The purpose of the LMS is to allow for the easy notification of applications that they should attempt to clean up or reduce their memory memory consumpt- ion or face a complete absence of available memory. For example, a graphics or sound editor may elect to be notified that memory is becoming scare and if so notified will deallocate space used to hold sounds or graphics no longer in current use by the user but which were re- tained in ram as a performance boost in the event that the user would elect to reuse the data at a later time. The ASDG LMS provides a reliable low memory notification service which will be tripped upon any failure of an AllocMem system call. Note: the ASDG LMS uses operating system mechanics already present in 1.2 - it does not alter or modify any system code - anywhere. Specifically, AllocMem is NOT touched. Notification is performed via the natural interprocess communications prim- itive available on the Amiga, the message. Support for the ASDG LMS is intended to be coded into your application. The remainder of this document is an explanation of how this is done. 4. As A Programmer, What Do You Agree To Do? ----------------------------------------------------------------------------- You agree (by writing your code correctly) to the following things: (a) You will allocate and initialize a message port to be used by the ASDG LMS to notify you. (b) You will allocate and initialize a LowMemMsg structure which will be used BY the ASDG LMS to notify you. (c) To be effective, you agree to monitor your LMS message port in all of your calls to Wait. (d) You agree to call DeRegLowMemReq when exiting, prior to closing the ASDG LMS library. (e) You agree to close the ASDG LMS library when done. (f) You agree to reinitialize your LowMemMsg each time the ASDG LMS notifies you of memory shortages. (g) You agree to examine the return code from RegLowMemReq. This routine is your interface to the Low Memory Server registration list. It will tell you if the message port name you supplied has already been used by someone else. If you fail to do these things, there isn't much point in using the ASDG LMS. 5. The LMS Message Port ----------------------------------------------------------------------------- You must allocate and initialize a message port to which the LMS will send you its low memory notification message. You may do this in the usual way. However, you must be prepared to delete this message port and re-allocate it as many times as is needed to get a unique message port name. After defining the message port (with a name you hope will be unique) and defining a LowMemMsg (see later) you will register your message port name with the ASDG LMS by calling RegLowMemReq. This call may return an error value indicating that the message port name is not unique. Your request to register with the LMS has been denied and you must delete your message port and redefine one with another name (and loop to the call to RegLowMemReq a- gain). This ensures that only one port with any given name will be registered with the LMS. 6. The LowMemMsg ----------------------------------------------------------------------------- YOU have to allocate a LowMemMsg structure. This will be the message that LMS uses to notify you of a low memory condition. You define it rather than the LMS since if the LMS needs to get in touch with you, it is because there is a low memory situation present. Hardly the time to go allocating message storage. The LowMemMsg structure is defined in low-mem.h as is as follows: struct LowMemMsg { struct Message lm_msg; long lm_flag; }; This is simply a usual message structure with a long word flag tagged on the end. The only initialization YOU have to do is to set the lm_flag to a spec- ific value, LM_CONDITION_ACKNOWLEDGED. The LMS will initialize the rest of the message for you. Setting lm_flag to LM_CONDITION_ACKNOWLEDGED is cruicial to your receiving messages from the LMS. Immediately prior to sending you a message the LMS will (after verifying that your registered message port exists) interrogate your lm_flag. If it is not set to LM_CONDITION_ACKNOWLEDGED then the LMS will not send you the message. You are specifically NOT to Reply to the message you receive from the LMS. The LMS is being run directly from a failing AllocMem call by someone else's program. To prevent the possibility of a program NOT replying to the LMS's message (and thus deadlocking the system) I use the LM_CONDITION_ACKNOWLEDGED value in lm_flag to signify that your process has acknolwedged the receipt of its previous low memory message. Repeat - DO NOT REPLY TO THE LOW MEMORY MESSAGE - SET lm_flag INSTEAD! Here's the definition of LM_CONDITION_ACKNOWLEDGED: #define LM_CONDITION_ACKNOWLEDGED (('A'<<24)|('S'<<16)|('D'<<8)|'G') 7. Requesting Registration ----------------------------------------------------------------------------- After defining your message port to be used by the LMS to notify you of a low memory situation and defining a LowMemMsg structure, you register your message port and message structure with the ASDG LMS by calling the library routine ``RegLowMemReq''. The call takes the following form: Result = RegLowMemReq(PortName , PtrToLowMemMsg); d0 a0 a1 The call will return 0 if all went well. This return indicates that you will be receiving low memory warnings through the specified port. If, how- ever you do not receive a 0 result then something went astray with your registration request. Two error results are defined. These are: #define LM_BADNAME -1 /* duplication of port name */ #define LM_NOMEM -2 /* memory allocation failed */ If you receive LM_BADNAME then the ASDG LMS is telling you that someone has previously registered the same port name as you have just tried. Simply change the name and resubmit the request (taking into account the fact that you might have already allocated a port with the invalid name). The following flow chart indicates a reasonable way to choose a port name: Forbid() | | Choose A Name <----------\-----\ | | | | | | FindPort | | | | | | (yes) | | Port Already Defined?--------/ | | | | (no) | | | RegLowMemReq | | | | (yes) | (Note 1)---------->Fail?----------------------/ | | (no) | CreatePort | | Permit | v Note 1: This can happen since someone may have DeletePort'ed their message port but NOT canceled their reservation with the LMS by calling DeRegLowMemReq. 8. Requesting DeRegistration ----------------------------------------------------------------------------- As part of your program's exit process you should cancel your registration with the LMS. This is done by calling DeRegLowMemReq with the LMS port name as the only argument. If you do not call this routine before exiting AND some other process still has the LMS library open, the memory that the LMS library allocated to store your registration will not be freed. However, when the last process that has the LMS library open finally does close it, all remaining nodes (from people who didn't call DeRegLowMemReq) will be expunged along with the rest of the library. Summary of call: (void) DeRegLowMemReq(PortName); a0 9. Closing The LMS Library ----------------------------------------------------------------------------- It is absolutely critical that your close the LMS library before exiting your program. If you don't, the library's open count can never again go to zero causing the library to be unable to expunge itself from memory when otherwise no longer needed. While the LMS is very compact this is still not a wise thing to do. The LMS library is closed in the following way: CloseLibrary(LowMemBase); Note that the long integer LowMemBase must be declared somewhere in your ap- plication using the above spelling. 10. The lm_flag Again... ----------------------------------------------------------------------------- This chapter is here JUST to remind you that the LMS will look for a specif- if value in your lm_flag LowMemMsg field. If lm_flag is not LM_CONDITION_- ACKNOWLEDGED, then the LMS will not send you any more messages. 11. Hints For Using The ASDG LMS Effectively ----------------------------------------------------------------------------- If AllocMem detects that it is going to fail due to lack of memory, it will run the list of libraries calling each library's expunge routine in turn. The LMS upon having its expunge routine tickled will run through its list of registrations sending off messages to each registers message port in turn (the last thing you want here is to have LMS wait for a reply so it is written specifically NOT to - so don't reply to any messages that the LMS may send you). Some calls to AllocMem fail even when there's plenty of memory available. For example, a request to AllocMem for 2 megabytes of memory on a 512K Amiga will certainly fail even though there might be 400K still available. To really use the LMS effectively, the first thing your program should do is to actually interrogate the amount of memory available on the system by calling AvailMem. Thus, your program can tell the difference between a real memory emergancy and an AllocMem whose goals were unrealistic. 12. About The ASDG LMS ----------------------------------------------------------------------------- The ASDG Low Memory Server was written completely in Manx Assembly Language by Perry S. Kivolowitz, president of ASDG Incorporated. The LMS was written as part of the development of ASDG's update to Facc, FaccII. FaccII is a floppy accelerator providing performance from floppy disk far in excess of current hard disks (with some limitations of course). FaccII will use the LMS to determine when it should begin taking memory conservation measures. While FaccII is a commercial product, we have decided to release the LMS for non-commercial distribution (and licensed commercial distribution) be- we view the LMS as a useful generic tool which we feel the Amiga community as a whole would benefit from and, of course, we felt that doing this would be in the best interest of ASDG (besides why have everyone write their own and possibly have several of them running on the machine at once?) We feel ASDG has contributed as much to the betterment of the Amiga commun- ity as any other vendor or private contributor. The ASDG Recoverable Ram Disk, tutorials in Amazing Computing, and now the LMS are examples of our love and committment for the Amiga personal computer and the Amiga using community. This is our small way of showing that, yes, we put back in and not just take out.