home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / !Help < prev    next >
Encoding:
Text File  |  1997-01-20  |  7.7 KB  |  245 lines
  1.     Desk release 3.10 (20 Jan 1997)
  2.     •••••••••••••••••••••••••••••••
  3.  
  4.  
  5.  
  6. Introduction
  7. ————————————
  8.  
  9. Desk is a new version 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 a few 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.
  88.  
  89. I think there is a problem in that this will catch SIGSTACK - the error
  90. handler is compiled with standard stack-checking, so an infinite loop
  91. will result...
  92.  
  93. Note that you are forced to use the Error2-system when using Desk - any
  94. error not caught (eg because you didn't call Desk_Error2_Init_JumpSig())
  95. will halt the program.
  96.  
  97.  
  98.  
  99.  
  100. Directory structure
  101. ———————————————————
  102.  
  103. Everything is in a 'Desk' directory, rather than an application
  104. directory, which is intended to be put into C$Path. Hence headers are
  105. included with '#include "Desk.Wimp.h"'. This means that Desk is a more
  106. conventional library, rather than setting its own system variables etc
  107. which is rather unnecessary I think.
  108.  
  109. Source code is /within/ the .o directory, which may seem a little
  110. strange. It is also within a '!DeskSrc' application directory, so the
  111. code can be compiled with complete filenames using the
  112. 'Desk_Sources$Dir' system variable, which can aid debugging.
  113.  
  114. Building the various versions of Desk is done with my freeware 'Makatic'
  115. tools, which cuts down the number of obscure script files that were in
  116. DeskLib.
  117.  
  118.  
  119.  
  120.  
  121. Changes to sublibraries
  122. ———————————————————————
  123.  
  124. The file 'Desk.History' contains a list of all changes since DeskLib
  125. 2.30. Due to extreme lack of time, many changes since DeskLib betas have
  126. not been documented particularly well.
  127.  
  128.  
  129.  
  130.  
  131. Other things
  132. ————————————
  133.  
  134. All code that used to call DeskLib's 'SWI' function now uses Acorn's
  135. '_swi'. One reason is that SWI would have to be modified (albeit fairly
  136. trivially) to work on the StrongARM. More importantly for me, SWI isn't
  137. ROM-able. Also, I think _swi is a lot easier to use.
  138.  
  139. I haven't built a SDLS version of Desk. The Jump library has untested
  140. support for the expensions to longjmp required by SDLS.
  141.  
  142. There are several versions of the library:
  143.  
  144.     C:Desk.o.Desk        Normally compiled.
  145.     C:Desk.o.Desk_D        Compiled with Desk_DEBUG predefined, so
  146.                 Desk_Debug_Printf statements are active.
  147.     C:Desk.o.Desk_M        Compiled with cc -zM, for use in module
  148.                 code.
  149.     C:Desk.o.Desk_M_D    Compiled with cc -zM and Desk_DEBUG
  150.                 predefined.
  151.     C:Desk.o.Desk_MC    Compiled for use with MemCheck, plus
  152.                 with cc -g, so can be used with DDT.
  153.     C:Desk.o.Desk_FN    Compiled with embeded function names.
  154.  
  155.  
  156.  
  157.  
  158. ToDo
  159. ————
  160.  
  161. Auto-Freeing of resources after errors
  162.     
  163.     Resources have to be explicitly released whenever an error occurs, which
  164.     results in code like:
  165.     
  166.         {
  167.         void* volatile    ptr = NULL;
  168.         Desk_Error2_Try    {
  169.             ...
  170.             ptr = Desk_DeskMem_Malloc( ...);
  171.             ...
  172.             }
  173.         Desk_Error2_Catch    {
  174.             Desk_DeskMem_Free( ptr);
  175.             Desk_Error2_ReThrow();
  176.             }
  177.         Desk_Error2_EndCatch
  178.         
  179.         ...
  180.         }
  181.     
  182.     I have found this sort of code to occur very commonly. The problem is
  183.     that it is rather longwinded, and the call to setjmp made by
  184.     Desk_Error2_Try is probably rather slow (it has to save all registers
  185.     etc, and restricts the optimising that the compiler can carry out).
  186.     
  187.     Note that not using Desk_Error2 would still require 'ptr' to be freed in
  188.     case of error. One common way of doing this is to use the dreaded goto:
  189.     
  190.         {
  191.         void*    ptr = NULL;
  192.         os_error*    e;
  193.         ptr = malloc( ...);
  194.         if ( !ptr)    { e=...; goto error; }
  195.         if ( e=Foo( ...), e)    goto error;
  196.         if ( e=Bar( ...), e)    goto error;
  197.         ...
  198.         return NULL;
  199.         
  200.         error:
  201.         free( ptr);
  202.         return e;
  203.         }
  204.     
  205.     so the Desk_Error2 system isn't making code more difficult to write
  206.     really.
  207.     
  208.     Anyway, a way to avoid the try..catch blocks would be to make
  209.     Desk_DeskMem_Malloc put every malloc block in a singly-linked list, and
  210.     make Desk_Error2_Try store the last malloc block. Then when an error
  211.     occurrs, Desk_JumpAuto_Throw would automatically free all blocks up to
  212.     (and not including) the block registered by the last Desk_Error2_Try.
  213.     
  214.     This scheme could be extended to automatically call fclose() etc. It has
  215.     the drawback of adding a one word overhead to every malloc block.
  216.     
  217.     Note that in normal operation, no automatic freeing of blocks would
  218.     occur. If some allocated memory was required to be preserved even after
  219.     an error occurred, it would have to be allocated using something like
  220.     Desk_DeskMem_MallocPermanent() or something.
  221.     
  222.  
  223. Make Save library use Export.
  224.  
  225. Make SDLS version.
  226.  
  227. Use RCS.
  228.  
  229. Lots of other things...
  230.  
  231.  
  232.  
  233. Important note
  234. ——————————————
  235.  
  236. Even though I now work for Acorn, Desk has nothing to do with Acorn.
  237. It's status is the same as DeskLib - a freeware library supplied with
  238. all source and no support 8) .
  239.  
  240.  
  241. - Julian Smith
  242.  
  243. jsmith@acorn.co.uk
  244.  
  245.