home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / desk / core / Desk / !Help next >
Encoding:
Text File  |  1997-05-20  |  8.0 KB  |  249 lines
  1.     Desk release 3.11 (24 Jan 1997)
  2.     •••••••••••••••••••••••••••••••
  3.  
  4.  
  5.  
  6. Introduction
  7. ————————————
  8.  
  9. Desk is development of the DeskLib library. The main changes are error
  10. handling, names, the directory structure, and an extra build for module
  11. code. There are also new functions and sub-libraries.
  12.  
  13. The reason for the new library is that it wasn't possible to update
  14. DeskLib to use the new error handling while preserving backwards
  15. compatibility.
  16.  
  17. I'm fully aware that releasing an incompatible version of a wildly used
  18. library like DeskLib may be unpopular, but it was already proving
  19. difficult to add certain types of code to DeskLib because of it's
  20. primitive error handling, so making radical changes had to happen at
  21. some stage.
  22.  
  23.  
  24.  
  25. Names
  26. —————
  27.  
  28. Every function, variable, typedef etc etc name has been prefixed with
  29. 'Desk_'. Thus 'Desk_Event_Initialise', 'Desk_Wimp_Poll' etc.
  30.  
  31. This has been done so that Desk can be used with other libraries without
  32. name-clashes. For example, DeskLib's Wimp_ veneers clash badly with the
  33. #defines used by OSLib, RISC_OSLib and Acorn's "swis.h" etc.
  34.  
  35. Also, the new error-handling means that Desk functions behave slightly
  36. differently from the equivalent DeskLib ones (eg they don't return an
  37. error code), so the names have to be different.
  38.  
  39. The new names are 5 characters longer which might seem clumsy, but I
  40. think that the benefits more than compensate for this. It would be a
  41. relatively simple task to write some headers which macro Desk's names to
  42. the old DeskLib names without the prefix.
  43.  
  44. Also, all variables such as 'event_taskhandle' are now called
  45. 'Desk_Event_taskhandle' rather than 'Desk_event_taskhandle'. The
  46. capitalised 'Event' means that the object occupies memory, as opposed to
  47. structure names such as 'Desk_event_pollblock'.
  48.  
  49. Note that all structure field-names are identical to the DeskLib ones.
  50.  
  51. The Obey files Desk.Bin.ConvertSrc and Desk.Bin.ConvertSr2 can be used
  52. with sed to roughly convert DeskLib source code to use the new names.
  53. The conversion isn't perfect, so the converted code will need tidying
  54. up, but these scripts will save a lot of donkey work.
  55.  
  56.  
  57.  
  58.  
  59. Error handling
  60. ——————————————
  61.  
  62. Most functions have been changed to make use of the 'Error2' sublibrary,
  63. which was introduced in DeskLib betas after DeskLib release 2.30.
  64.  
  65. All (not quite all yet) swi veneers now send any error straight to the
  66. Error2 system. This is done either by calling the non-X form and relying
  67. on the C runtime system to convert any error into a signal which can be
  68. caught by Error2, or calling the X form and then branching to
  69. Desk_Error2_CheckOS if the V flag is set.
  70.  
  71. The first method is slightly simpler, but doesn't work in SVC mode (the
  72. C runtime system doesn't convert OS errors to a signal in SVC) so is
  73. only used for Wimp SWIs which will always (I think) be called from USR
  74. mode (for example, the task part of module-tasks still run in USR mode).
  75.  
  76. It would have been possible to put some conditional assembley so that
  77. the non-X form is used for non-module builds of the library, but this is
  78. a lot of hastle, and the branch to the Error2 handling after an X SWI is
  79. only one instruction (it's a macro in 'C:Desk.sh.Macros').
  80.  
  81. This means that code can use C++-style exception handling (see the
  82. Jump.h and JumpAuto.h files), so you can malloc memory, call library
  83. functions etc etc without worrying about error-return codee after every
  84. function call.
  85.  
  86. The client application is required to call Desk_Error2_Init_JumpSig() to
  87. initialise the error system. If this isn't done, then any error will
  88. halt the program.
  89.  
  90. I think there is a problem in that this will catch SIGSTACK - the error
  91. handler is compiled with standard stack-checking, so an infinite loop
  92. will result...
  93.  
  94. Note that you are forced to use the Error2-system when using Desk - any
  95. error not caught (eg because you didn't call Desk_Error2_Init_JumpSig())
  96. will halt the program.
  97.  
  98.  
  99.  
  100.  
  101. Directory structure
  102. ———————————————————
  103.  
  104. Everything is in a 'Desk' directory, rather than an application
  105. directory, which is intended to be put into C$Path. Hence headers are
  106. included with '#include "Desk.Wimp.h"'. This means that Desk is a more
  107. conventional library, rather than setting its own system variables etc
  108. which is rather unnecessary I think.
  109.  
  110. Source code is /within/ the .o directory, which may seem a little
  111. strange. It is also within a '!DeskSrc' application directory, so the
  112. code can be compiled with complete filenames using the
  113. 'Desk_Sources$Dir' system variable, which can aid debugging.
  114.  
  115. Building the various versions of Desk is done with my freeware 'Makatic'
  116. tools, which cuts down the number of obscure script files that were in
  117. DeskLib.
  118.  
  119.  
  120.  
  121.  
  122. Changes to sublibraries
  123. ———————————————————————
  124.  
  125. The file 'Desk.History' contains a list of all changes since DeskLib
  126. 2.30. Due to extreme lack of time, many changes since DeskLib betas have
  127. not been documented particularly well.
  128.  
  129.  
  130.  
  131.  
  132. Other things
  133. ————————————
  134.  
  135. All code that used to call DeskLib's 'SWI' function now uses Acorn's
  136. '_swi'. One reason is that SWI would have to be modified (albeit fairly
  137. trivially) to work on the StrongARM. More importantly for me, SWI isn't
  138. ROM-able. Also, I think _swi is a lot easier to use.
  139.  
  140. I haven't built a SDLS version of Desk. The Jump library has untested
  141. support for the expensions to longjmp required by SDLS.
  142.  
  143. There are several versions of the library:
  144.  
  145.     C:Desk.o.Desk        Normally compiled.
  146.     C:Desk.o.Desk_D        Compiled with Desk_DEBUG predefined, so
  147.                 Desk_Debug_Printf statements are active.
  148.     C:Desk.o.Desk_M        Compiled with cc -zM, for use in module
  149.                 code.
  150.     C:Desk.o.Desk_M_D    Compiled with cc -zM and Desk_DEBUG
  151.                 predefined.
  152.     C:Desk.o.Desk_DDT    Compiled with cc -g and Desk_DEBUG
  153.                 predefined, for use with DDT.
  154.                 This version may hasn't been build yet.
  155.     C:Desk.o.Desk_MC    Compiled for use with the commercial
  156.                 MemCheck, plus with cc -g, so can be
  157.                 used with DDT. Note that this version
  158.                 cannot be rebuilt without !MemCheck.
  159.     C:Desk.o.Desk_FN    Compiled with embeded function names.
  160.  
  161.  
  162.  
  163.  
  164. ToDo
  165. ————
  166.  
  167. Auto-Freeing of resources after errors
  168.     
  169.     Resources have to be explicitly released whenever an error occurs, which
  170.     results in code like:
  171.     
  172.         {
  173.         void* volatile    ptr = NULL;
  174.         Desk_Error2_Try    {
  175.             ...
  176.             ptr = Desk_DeskMem_Malloc( ...);
  177.             ...
  178.             }
  179.         Desk_Error2_Catch    {
  180.             Desk_DeskMem_Free( ptr);
  181.             Desk_Error2_ReThrow();
  182.             }
  183.         Desk_Error2_EndCatch
  184.         
  185.         ...
  186.         }
  187.     
  188.     I have found this sort of code to occur very commonly. The problem is
  189.     that it is rather longwinded, and the call to setjmp made by
  190.     Desk_Error2_Try is probably rather slow (it has to save all registers
  191.     etc, and restricts the optimising that the compiler can carry out).
  192.     
  193.     Note that not using Desk_Error2 would still require 'ptr' to be freed in
  194.     case of error. One common way of doing this is to use the dreaded goto:
  195.     
  196.         {
  197.         void*    ptr = NULL;
  198.         os_error*    e;
  199.         ptr = malloc( ...);
  200.         if ( !ptr)    { e=...; goto error; }
  201.         if ( e=Foo( ...), e)    goto error;
  202.         if ( e=Bar( ...), e)    goto error;
  203.         ...
  204.         return NULL;
  205.         
  206.         error:
  207.         free( ptr);
  208.         return e;
  209.         }
  210.     
  211.     so the Desk_Error2 system isn't making code more difficult to write
  212.     really.
  213.     
  214.     Anyway, a way to avoid the try..catch blocks would be to make
  215.     Desk_DeskMem_Malloc put every malloc block in a singly-linked list, and
  216.     make Desk_Error2_Try store the last malloc block. Then when an error
  217.     occurrs, Desk_JumpAuto_Throw would automatically free all blocks up to
  218.     (and not including) the block registered by the last Desk_Error2_Try.
  219.     
  220.     This scheme could be extended to automatically call fclose() etc. It has
  221.     the drawback of adding a one word overhead to every malloc block.
  222.     
  223.     Note that in normal operation, no automatic freeing of blocks would
  224.     occur. If some allocated memory was required to be preserved even after
  225.     an error occurred, it would have to be allocated using something like
  226.     Desk_DeskMem_MallocPermanent() or something.
  227.     
  228.  
  229. Make SDLS version.
  230.  
  231. Use RCS.
  232.  
  233. Lots of other things...
  234.  
  235.  
  236.  
  237. Important note
  238. ——————————————
  239.  
  240. Even though I now work for Acorn, Desk has nothing to do with Acorn.
  241. It's status is the same as DeskLib - a freeware library supplied with
  242. all source and no support 8) .
  243.  
  244.  
  245. - Julian Smith
  246.  
  247. jsmith@acorn.co.uk
  248.  
  249.