home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / FOXPRO / FFAQ / ALLOC.FAQ next >
Text File  |  1992-04-10  |  9KB  |  241 lines
  1.     FORCE FAQ (Frequently Asked Questions)   (alloc.faq 1.1)         1
  2.     ------------------------------------------------------------------
  3.  
  4.     Advanced Topic: FORCE's memory allocation routines
  5.  
  6.     Author: David Holmes
  7.  
  8.     Assumed Knowledge:
  9.         I'm going to assume that you know what pointers are and
  10.     hopefully you've at one point or another used functions like
  11.     C's malloc(), or new() in Pascal or C++.
  12.  
  13.     Examples: Fsort, iCopy, Heap library
  14.  
  15.     General discussion and easy FAQ answers:
  16.     -----------------------------------------------------------------
  17.     Q:    Ack!  I heard someone talking about FORCE's malloc()
  18.         function, but I can't find it anywhere!
  19.  
  20.     A:    That's because this is one of FORCE's internal routines.
  21.     Actually, it's not even that.  malloc(), calloc(), realloc(),
  22.     free(), and some other routines were added to the FORCE library
  23.     when FORCE was made compatible with the Microsoft and Borland C
  24.     libraries.  They weren't really intended to be called from FORCE
  25.     functions, because they deal with pointers, and pointers can be
  26.     difficult to use in FORCE.
  27.  
  28.         I've provided a header file called ALLOC.HDR that gives
  29.     the FORCE prototypes for malloc(), calloc() etc, but stay with me,
  30.     because there are some things that you'll need to know before you
  31.     start dynamically allocating FORCE memory.
  32.  
  33.         FORCE has several internal memory handling routines that
  34.     were designed to be called from other assembly language routines.
  35.     In order to get C functions that called the standard C memory
  36.     routines to work with FORCE, several functions were designed as
  37.     "wrappers" around the FORCE internal routines.  Some work, and
  38.     some are just for show, having no real equivalent in FORCE.
  39.  
  40.         For example, the malloc() routine does nothing more than
  41.     convert the given number of bytes into paragraphs, and then
  42.     calls the internal function _$allocate with service 1.  Then it
  43.     returns the pointer to the memory (don't try this yourself).
  44.     The free() routine is even simpler.  It just passes the memory
  45.     pointer to a function called _$deallocate and let's it deal
  46.     with freeing the memory (don't try that yourself either).
  47.  
  48.         However, there are some differences between the FORCE
  49.     allocation functions and their C equivalents.  First and
  50.     foremost, if you call either malloc() or calloc() and there is
  51.     not enough memory to fulfill your request, you will get error
  52.     #275 (memory chain destroyed) if you're lucky, or most likely
  53.     your computer will just lock up.  There's another function
  54.     called realloc() which looks like it should work correctly,
  55.     but I've had so much difficulty with it that I've removed it
  56.     from there header file.
  57.  
  58.  
  59.     ------------------------------------------------------------------
  60.                                                                      1
  61.     FORCE FAQ (Frequently Asked Questions)                           2
  62.     ------------------------------------------------------------------
  63.         Because of these problems, I've written two functions
  64.     called alloc() and kalloc() which replace malloc() and calloc().
  65.     They are exactly like their counterparts except that they check
  66.     the free memory before calling the FORCE internal memory
  67.         functions.  You'll find them in the header file, and the library,
  68.         object code, and the source code will be included with this
  69.     special edition of the FAQ.  Also included is another function
  70.     called mavail() which returns the available memory.
  71.  
  72.     FORCE Memory allocation functions usage:
  73.     ------------------------------------------------------------------
  74.  
  75.         Both malloc() and calloc() return a four byte pointer to
  76.     newly allocated memory in the classic SEGMENT:OFFSET style.
  77.     Fortunately, this corresponds to a FORCE LONG integer.  Suppose
  78.     we wanted to allocate a 5k read buffer.  The code would look like
  79.     this:
  80.  
  81.         VARDEF
  82.             LONG        buffer
  83.             UINT        buf_size
  84.         ENDDEF
  85.  
  86.         buf_size = 5120
  87.         buffer = malloc( 5120 )
  88.  
  89.         * or you could use calloc(), like this:
  90.         *
  91.         * buffer = calloc( 5, 1024 )
  92.  
  93.     Pretty simple, right?  Allocating the memory isn't the tough
  94.     part.  The tough part about pointers in FORCE is what to
  95.     do with that read buffer now that you have it.  For example,
  96.     you cannot simply start writing to it, like this:
  97.  
  98.         fb_read( fhandle, buffer, buf_size )    && compiler error
  99.  
  100.     In order to dereference a pointer, you must pass the pointer
  101.     as a VALUE, and receive it in another module as something else.
  102.  
  103.     In the sample code iCopy.prg, you'll see exactly how we do it.
  104.     In the iCopy module, you'll find the line
  105.  
  106.     buffer = kalloc( i, &PAGESIZE )
  107.  
  108.     which allocates the buffer.  Then the pointer is passed as a
  109.     VALUE LONG to the function iCopy_File(), which receives it
  110.     like this:
  111.  
  112.     PROCEDURE iCopy_File
  113.         PARAMETERS BYTE read_buffer
  114.  
  115.     Now that we have the read buffer, we can use it like this:
  116.  
  117.         fb_read( fhandle, read_buffer, buf_size )
  118.  
  119.     ------------------------------------------------------------------
  120.                                                                      2
  121.     FORCE FAQ (Frequently Asked Questions)                           3
  122.     ------------------------------------------------------------------
  123.     The reason that this works is related to the way that FORCE
  124.     passes parameters.  Unless the parameter is modified by the
  125.     VALUE modifier, FORCE will pass the ADDRESS of the parameter,
  126.     not the PARAMETER itself.  In the above example, we passed
  127.     a VALUE LONG and received it as a BYTE address.
  128.  
  129.     I realize that this is a sloppy way to do things, because you
  130.     have to write prototypes that don't match their functions and
  131.     put them in other modules.  But that's why this is advanced
  132.     topic.
  133.  
  134.     Analysis of the Example Code:
  135.     ------------------------------------------------------------------
  136.         In this special edition of the FAQ, you'll find three
  137.     examples of how to use the FORCE memory allocation routines.
  138.  
  139.         The first is the iCopy program, which copies files from
  140.     one place to another, but has an indicator that progresses as the
  141.     copy progresses.  This is nice for those times when you have to
  142.     copy the JD library to a floppy.  By the way, it's about twice
  143.     as fast as the system copy because it uses a larger copy buffer,
  144.     but you'll only notice it for large files.  To get the usage
  145.     for the iCopy program just 'Make' it with Jmake and then type
  146.     iCopy with no parameters.
  147.  
  148.         The second example is Fsort, which is a replacement of
  149.     the system SORT command.  It started out as another example
  150.     of how to use malloc() and calloc(), but I later decided to go
  151.     all out and write a non-constrained heap manager that basically
  152.     acts as a dynamic array (we'll come to this in a minute).  Like
  153.     the system SORT command, Fsort's only function is to sort a
  154.     sequence of strings.  Fsort does this by reading in the given
  155.     files ( or the STD_IN handle if there are none ), and creating
  156.     a giant array of pointers to each of the strings in the input.
  157.     Then it sorts the array with a Quick_Sort algorithm, which is
  158.     probably why it's twice as fast as the system SORT, which must
  159.     use a slower algorithm such as the Shell_Sort, or the Insertion-
  160.     Sort.
  161.  
  162.         The final example is a non-constrained heap library.  By
  163.     non-constrained I mean that it doesn't keep a standard heap
  164.     ordering property, and the items added are just appended to the
  165.     current heap.  I realize that its tough to call it a heap if it
  166.     really isn't one, but it wouldn't be too tough to modify the
  167.     heap_insert() function to maintain the heap property.
  168.  
  169.         The source code and the library for the heap manager
  170.     are included here, along with a heap.faq file which further
  171.     details the usage of the library.
  172.  
  173.     ------------------------------------------------------------------
  174.                                                                      3
  175.     FORCE FAQ (Frequently Asked Questions)                           4
  176.     ------------------------------------------------------------------
  177.  
  178.     Final Comments:
  179.     ------------------------------------------------------------------
  180.     You'll find that the FORCE memory handling routines can finally
  181.     give you that last little bit of control that you always wanted
  182.     from FORCE... if you're willing to work a little harder to get
  183.     it.  If you're a hardcore FORCE fan (and if you've read this
  184.     far you must be), I'd suggest writing your own toolkits like
  185.     the heap library, which not only shows you how to fake pointers,
  186.     it shows you how to fake structures and pointers to pointers.
  187.     You can then have your toolkits deal with the pointers approp-
  188.     riately so that you won't have to worry about it.
  189.  
  190.         Once you have your toolkits, you'll speed up your
  191.     application development tenfold.
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.     ------------------------------------------------------------------
  240.                                                                      4
  241.