home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsp / rink010 / Docs / !Overview < prev    next >
Encoding:
Text File  |  1995-06-25  |  9.7 KB  |  233 lines
  1.  
  2. Overview of rink
  3. rink documentation, (c) Ben Summers 1995
  4.  
  5.  
  6. This document is organised as 'informal' questions and answers. Please read
  7. this before any of the other files which contain more formal usage
  8. instructions. You might find it helpful to browse the glossary file now.
  9.  
  10. See index for details of what each file contains.
  11.  
  12.  
  13. What is rink?
  14. ~~~~~~~~~~~~~
  15. rink is a run time linker.
  16.  
  17.  
  18. Er, right. So what is run time linking?
  19. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20. When you link a program with link, link takes all your object files (stored
  21. in your o directory) and makes them into one file along with any library
  22. modules it needs.
  23.  
  24. After it has done this, it 'links' all the function calls together so that
  25. when you call a function, it actually calls it. You see, in the object
  26. files, the compiler doesn't create proper branch instructions because it
  27. doesn't actually know where the functions it's called are, so it creates
  28. relocations.
  29.  
  30. link goes along and relocates everything according to these relocations.
  31. After it's assembled all the objects into one file it knows where everything
  32. is so it can replace the function calls the compiler generated with real
  33. ones.
  34.  
  35. This is all very well and good, but it means you can't load more of this
  36. object code in and run it because it won't have it's relocations relocated.
  37.  
  38. This is where rink comes in. It can load more code in, and then link that to
  39. functions within your program. This is run time linking - instead of
  40. creating all the links at link time just after compliation, some of the
  41. links are linked at run time when you actually run the program.
  42.  
  43.  
  44. OK, I think I've got that now. So, what would I use it for?
  45. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46. Quite a lot of programs perform several distinct functions which are
  47. controlled in a similar way.
  48.  
  49. For example, imagine a program which converts between different file
  50. formats. It'll have a few routines to provide a user interface, and then
  51. more to convert between different file formats.
  52.  
  53. For example, you might have routines in each convertor to
  54.  
  55.     * Initialise it
  56.  
  57.     * Get some info on what it can convert
  58.  
  59.     * Identify files
  60.  
  61.     * Set up some options
  62.  
  63.     * Perform a conversion
  64.  
  65. Each convertor does a very different thing, but they all have the same set
  66. of functions to control them, and the calling code doesn't need to know the
  67. details of what they're doing.
  68.  
  69. Now, if you put all these convertors into your main program, you then can't
  70. extend your program to do more conversions with recompiling it, and when you
  71. load your program you have to load all the convertors, whether or not you
  72. want to use them. This means your program is larger. And perhaps more
  73. importantly, other people can't extend your program to do more conversions
  74. without access to your code...
  75.  
  76. You might think it would be a good idea to store the convertors on disc
  77. seperately, and load them when you actually want to use them. And then maybe
  78. throw them away when you've finished with them to save memory.
  79.  
  80. This is exactly the sort of thing run time linking is useful for.
  81.  
  82. Other possible uses are
  83.  
  84.     * Extensible applications, where all the tools are seperate to the
  85.       application kernel.
  86.  
  87.     * Removing the necessity for code to be loaded all the time
  88.       (although overlays can often be a better thing to use).
  89.  
  90.     * Writing programs which other people can extend easily.
  91.  
  92. ... but this isn't a definative list. Once you understand what rink does,
  93. you'll probably be able to think of lots of other things you can do with it.
  94.  
  95. If you are familiar with C++, here's another way to think about it. If you
  96. have a base class which represents an interface to an entity, then if other
  97. objects can be represented as derived classes from this base class, then they
  98. are very much suitiable for being stored as rink segments.
  99.  
  100.  
  101. That sounds useful, but surely there are some things I can't use it for.
  102. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  103. If all the bits of code you want to load in have sepecific functions which
  104. the parent program must know about, you should think about other ways of
  105. achieving this, perhaps using overlays or splitting your code up into
  106. seperate programs.
  107.  
  108. However, you could still use rink so you get complete control of the loading
  109. and unloading of segments. rink just provides a method of loading code and
  110. calling functions - what you do with them is up to you.
  111.  
  112. The main thing rink cannot do is share one instance of code between
  113. applications to provide something like a shared library. This is because the
  114. code is linked to the application and there can only be one instance of the
  115. associated data.
  116.  
  117. However, you could use something like a module to load in your code and
  118. provide your own API to call shared code, but you must not use static data,
  119. instead passing in a data block on each call.
  120.  
  121.  
  122. What about modules?
  123. ~~~~~~~~~~~~~~~~~~~
  124. Yes, you can use rink in modules. Just remember to use the module code option
  125. on your segments as well as the main module code.
  126.  
  127.  
  128. How does rink work?
  129. ~~~~~~~~~~~~~~~~~~~
  130. The actual rink program prepares object files for run time linking. First,
  131. it uses link to combine all the object files you give it into one AOF file,
  132. and perform internal relocations (relocations which link to data and
  133. functions within the object code). rink then works out what links need to be
  134. performed at run time, and writes a compact file describing the links and a
  135. code file. These two files allow the code to be loaded and linked into the
  136. parent program.
  137.  
  138. Instead of referencing functions by name, it references them by index into a
  139. list of functions. This list is the pointer block map. Reference by index
  140. means that the overhead of this table is minimal. The table for all the
  141. symbols in the shared C library is just over 1K long. The links are thrown
  142. away after loading the code.
  143.  
  144. A typical rink segment is stored in a directory containing a code and a link
  145. file, and any other resources necessary. However, the program is free to
  146. store them anyway it chooses.
  147.  
  148. The parent program has the rink run time system linked into it. This loads
  149. the segments, and provides access to function pointers within it.
  150.  
  151.  
  152. Won't it be more difficult to write code that's loaded it at run time?
  153. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  154. No, not really. You compile your code to be run time linked with exactly the
  155. same compiler options as the main code and include header files in exactly
  156. the same way. You call functions just as you would in ordinary code.
  157.  
  158. The difference only comes when you come to link the code. Instead of using
  159. link, you use rink, and provide a file (the header description file) telling
  160. rink what to do with it. This file gives details on, amoung other things,
  161. the functions to place in the header. These functions are the functions you
  162. can call from the parent program. You can usually use the same header
  163. description file for every segment.
  164.  
  165. As well as a standard set of functions, you can also include named
  166. functions so you can be as flexible as you need.
  167.  
  168. You can access both code and data in the parent program as long as their
  169. names are included in the pointer block.
  170.  
  171.  
  172. Well then, won't it be more difficult to call it?
  173. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  174. This is slightly different, but still quite easy to do. You are provided
  175. with functions to load a rink segment, and a function to find a pointer to a
  176. function within the segment. All you do is just treat that pointer as a
  177. normal C function pointer.
  178.  
  179. Have a look at the demonstration program, which shows just how easy it is to
  180. use.
  181.  
  182.  
  183. Doesn't run time linking have a bit of a performance hit?
  184. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  185. Function calls from the segment to the parent have no performance hit, as
  186. once they are loaded they are functionally identical to code linked in at
  187. compile time. If you cache the pointers to functions in the segments, then
  188. the performance hit for a parent to segment is just the same as calling a
  189. function through a pointer in normal code.
  190.  
  191.  
  192. Do I have to use a specific language to be able to use rink?
  193. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  194. No. rink only requires APCS compilance to function, so any language compiler
  195. which produces APCS compilant AOF files can be used, including assembler.
  196.  
  197. The rink run time system requires memory allocation and free functions and
  198. optionally a error translation function. These are by default bound to
  199. malloc(), free() and an internal routine respectively, but you can bind them
  200. to other functions using command line options to rinkptr.
  201.  
  202. With C++, you will have to use mangled names in the header description or
  203. use C style functions for the interface.
  204.  
  205. You do not need to use the shared C library. You could use something like
  206. UnixLib - just scan the relevant stubs or library file when creating the
  207. pointer block file.
  208.  
  209.  
  210. What conditions are there on distributing code which uses rink?
  211. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  212. There are no restricitions on distributing rink segments as these only
  213. contain your code. However, the parent program requires the rink run time
  214. system. There are a few restrictions on what you can do with this, depending
  215. on the status of your program. See the ReadMe file for more details on this.
  216.  
  217.  
  218. Why do you always spell it with a lower case 'r'?
  219. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  220. Because that's its name. It's what it's executable is called, and looks
  221. nicer when written. Humour me, and always spell it like that too.  :-)
  222.  
  223.  
  224. Well that's quite cool, but I have another question...
  225. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  226. If you look in the !ReadMe file, it'll tell you how to contact me. I'll do
  227. my best to answer you quickly and get you going, but obviously I can make no
  228. promises.
  229.  
  230. Have fun.
  231.  
  232.  
  233.