home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #7 / amigamamagazinepolishissue1998.iso / libs / safegirport.lha / SafeGIRPort / SafeGIRPort.doc < prev   
Text File  |  1995-02-14  |  5KB  |  101 lines
  1.     SafeGIRPort 1.0
  2.  
  3.     Written by Osma Ahvenlampi with changes by Mark Thomas
  4.     Public Domain (please, let it be free)
  5.     There is no warranty of its usefulness, fitness, or whatever.
  6.     Please use at your own risk.
  7.  
  8. BACKGROUND
  9.  
  10.     First there was PatchOGR.  It has some bugs, noted below.
  11.  
  12.     Next there was NewObtainGIRPort.  It has a bug, noted below.
  13.  
  14.     Now, we have SafeGIRPort, a small patch to the Intuition
  15.     ObtainGIRPort() call, making certain BOOPSI gadgets and hacks such
  16.     as MagicMenu and CycleToMenu work together nicely.
  17.  
  18.     After writing textfield.gadget, some people began to notice a
  19.     lockup condition (deadlock) when used with MagicMenu and
  20.     CycleToMenu.  I at first had a fix worked into a beta version of
  21.     the textfield gadget, but discussions with other programmers made
  22.     me realize my code was right, and the hacks were wrong.
  23.  
  24.     I wanted an external program to fix the problem, but I couldn't
  25.     see how it could be written from these hacks' point of view.  Then
  26.     after talking with someone (Marcel I think was his name, a fellow
  27.     developer) I realized I could do what I was doing inside the beta
  28.     gadget, but in a patch of an Intution function.  This was the key.
  29.  
  30. USAGE
  31.  
  32.     To install the patch, run SafeGIRPort from a CLI.  To keep the size
  33.     to an absolute minimum, it cannot be run from Workbench.
  34.  
  35.     You should add the line "Run <>NIL: SafeGIRPort <>NIL:" to your
  36.     S:User-Startup, to use this patch.
  37.  
  38.     After installing the patch, SafeGIRPort will stick around, waiting
  39.     for a CTRL-C signal, after which it will (if possible) remove the
  40.     patch and exit.  If another program has patched over SafeGIRPort,
  41.     it will flash the screen and refuse to quit until the other patch
  42.     has been removed and you send a CTRL-C again.
  43.  
  44. EXPLANATION
  45.  
  46.     This patch adds a safety check in the ObtainGIRPort() call, by
  47.     checking whether the layer of the GadgetInfo structure is already
  48.     locked.  If it is, the patch will simply return NULL (a valid
  49.     response from ObtainGIRPort() mind you).
  50.  
  51.     PatchOGR by Mark Thomas had two major problems.  First, it did not
  52.     check whether the GadgetInfo had a valid layer, but simply called
  53.     AttemptLockLayerRom() with a NULL layer.  This is not necessarily
  54.     illegal since GadgetInfo structures should always have a valid
  55.     layer, but it does help to check it anyway since there is some bad
  56.     code out there.  Secondly, it subsequently called ObtainGIRPort()
  57.     while while the layer was locked.  This is not illegal, but the RKM
  58.     recommends that Intiution functions not be called when layers are
  59.     locked.  It does not say it's strictly illegal.  (An illegal
  60.     Intiution function to call is one that causes renders or locks
  61.     itself.)
  62.  
  63.     (If anyone notices, PatchOGR was a modification of WBTitle, and
  64.     as with WBTitle was written in C to show how to use SetFunction()
  65.     from C.  It's pointless when you have a small patch, but it is
  66.     informative, I think.)
  67.  
  68.     NewObtainGIRPort by Osma Ahvenlampi fixed those two problems in
  69.     PatchOGR and was released in assembly (my absolute favorite).
  70.     However, it leaves a minimal window for a lockup condition, as the
  71.     GadgetInfo layer is unlocked before obtaining the RastPort from the
  72.     original ObtainGIRPort().  The probability of another task locking
  73.     the layer in between these two operations is small, and may not
  74.     warrant enclosing the patch inside Forbid()/Permit().  Only time and
  75.     use will tell if they'll be needed.  If you need to install the
  76.     safety blanket, the code is available to all three programs.
  77.  
  78.     SafeGIRPort is yet another attempt to fix bugs, and make the code
  79.     smaller and faster.  Actually the bug it fixes is not that great of
  80.     a problem and only occurs when you try to uninstall the patch.  If
  81.     you have a processor that has both data and instruction caches
  82.     turned on, NewObtainGIRPort would potentially crash since the caches
  83.     were not flushed after the patch was uninstalled.  Also, the patch
  84.     code itself has been optimized (and the other code too), with the
  85.     benefit of less impact on any system performance.  At the same time
  86.     the small chance of the lockup condition mentioned above has been
  87.     made even smaller.  Finally, due to all the optimizations, there
  88.     was a total savings of 72 bytes of memory (gee aren't we all happy).
  89.  
  90.     I hope that the optimization and space savings continues.  This
  91.     program was designed to be exactly functionally equivalent to the
  92.     NewObtainGIRPort program, while being safer to use.
  93.  
  94. AUTHOR
  95.  
  96.     Email: <mthomas@zilker.net>
  97.  
  98.     Snailmail: Mark Thomas
  99.                1515 Royal Crest Drive #3259
  100.                Austin, TX  78741
  101.