home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c160 / 1.ddi / DOC / H4.DOC < prev    next >
Encoding:
Text File  |  1990-03-04  |  8.4 KB  |  253 lines
  1.  
  2. (c) Copyright Sequiter Software Inc. 1988-1990.  All rights reserved.
  3.  
  4.  
  5.  
  6. Memory Handling Routines
  7.  
  8. This module provides memory handling for Code Base's 
  9. Database, Index File, Block, Windowing, Menuing and Get memory structures.  Using 
  10. this memory handler, there is no Code Base specified limit to the 
  11. number of opened databases or opened index files.  In addition, small 
  12. chunks of memory can be allocated and freed with little overhead.
  13.  
  14. The first two integers of each chunk of memory are reserved 
  15. as pointers.  These pointers are used to create double linked lists 
  16. of allocated memory chunks.
  17.  
  18.  
  19.  
  20.  
  21. h4add()
  22.  
  23. Usage           int  h4add( char ** ptr_ref_ptr, 
  24.                             int mem_ref, int add_ref, 
  25.                             int add_before ) 
  26.   
  27. Description     'h4add' adds an allocated memory chunk to a double linked
  28.                 list.  It should not already be on one. 
  29.  
  30. Parameters      Name           Use 
  31.  
  32.                 ptr_ref_p      A pointer to the base memory pointer.  This
  33.                                is the same value as was initially passed to
  34.                                routine 'h4create'. 
  35.  
  36.                 mem_ref        A reference integer to the memory chunk. 
  37.  
  38.                 add_ref        The reference number to the memory chunk to
  39.                                be inserted into the double linked list either
  40.                                before or after 'mem_ref'. 
  41.                
  42.                 add_before     This value is '(int) 1' (true) if the memory
  43.                                chunk is to be before 'mem_ref' and is '(int) 0'
  44.                                (false) if the memory chunk is to be after
  45.                                'mem_ref'. 
  46.  
  47. Returns         The value in parameter 'add_ref'. 
  48.  
  49. See Also        'h4remove'
  50.  
  51.  
  52.  
  53.  
  54.  
  55. h4alloc()
  56.  
  57. Usage           char *  h4alloc( (unsigned int) num_bytes )   
  58.  
  59. Description     'h4alloc' allocates 'num_bytes' of memory and
  60.                 returns a pointer to allocated memory.  The 
  61.                 allocated memory is completely initialized 
  62.                 to zeros.  
  63.  
  64. Returns         Normally, 'u4error' exits if there is not enough
  65.                 memory.  However, if 'u4error' has been modified to 
  66.                 return rather than exit, 
  67.                 'h4alloc' will return '(char *) 0' if no
  68.                 additional memory is available.  
  69.  
  70.  
  71.  
  72.  
  73. h4create()
  74.  
  75. Usage           int  h4create( char ** ptr_ref_ptr, 
  76.                       int units, int size, int expand_units) 
  77.  
  78. Description     'h4create' does the initializing of a  memory structure to
  79.                 be used with the Code Base memory handler. 
  80.  
  81. Parameters      Name                  Use 
  82.  
  83.                 ptr_ref_ptr       This is a pointer to the base memory pointer
  84.                                   for the memory structure. 
  85.                
  86.                 units             The number of chunks to be initially
  87.                                   allocated. 
  88.                
  89.                 size              The number of bytes in the memory
  90.                                   structure. 
  91.   
  92.                 expand_units      The number of chunks to expand the
  93.                                   structure by when there are no more chunks
  94.                                   available. 
  95.  
  96. Returns         A '(int) -1' is returned to indicate the requested memory is
  97.                 not available.  This error will only occur if 'u4error' has been
  98.                 modified not to exit on an out of memory error.
  99.  
  100.  
  101.  
  102.  
  103.  
  104. h4free()
  105.  
  106. Usage           int  h4free( char ** ptr_ref_ptr, 
  107.                             int mem_ref ) 
  108.                  
  109. Description     'h4free' returns a chunk of memory to the pool of available
  110.                 memory. 
  111.  
  112. Parameters      Name          Use 
  113.  
  114.                 ptr_ref_p     A pointer to the base memory pointer.This is
  115.                               the same value as was initially passed to routine
  116.                               'h4create'. 
  117.  
  118.                 mem_ref       A reference integer to the storage being freed.
  119.                               This is the same integer which was returned by
  120.                               'h4get'. 
  121.  
  122. Returns         The reference integer to the previous memory chunk is returned. 
  123.                 If a previous chunk does not exist, a reference integer to the
  124.                 next memory chunk will be returned.  If there is no next memory
  125.                 chunk, '(int) -1' is returned.
  126.  
  127.  
  128.  
  129. h4free_chain()
  130.  
  131. Usage           void  h4free_chain( char ** ptr_ref_ptr, 
  132.                             int mem_ref ) 
  133.  
  134.                 'h4free_chain' calls 'h4free' repeatedly to free an entire
  135.                 chain of memory.  This routine can be used as an example for
  136.                 'h4free'. 
  137.  
  138. Example         /* Source for 'h4free_chain' */ 
  139.  
  140.                 void  h4free_chain( ptr_ref_ptr, mem_ref ) 
  141.                 char **ptr_ref_ptr ; 
  142.                 int   mem_ref ; 
  143.                 { 
  144.                    while ( mem_ref = 0 ) 
  145.                       mem_ref =  h4free( ptr_ref_ptr, mem_ref ) ; 
  146.                 }
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153. h4free_memory()
  154.  
  155. Usage           void  h4free_memory( void * ptr ) 
  156.                
  157. Description     This routine acts exactly like the 'free' routine in the
  158.                 standard library.  It is necessary because the 'free' routine is
  159.                 not available under the current version of Microsoft Windows.
  160.  
  161.  
  162.  
  163. h4get()
  164.  
  165. Usage           int h4get( char ** ptr_ref_ptr, int mem_ref )
  166.  
  167. Description     A chunk of memory is allocated.
  168.  
  169. Parameters      Name          Use
  170.  
  171.                 ptr_ref_p     A pointer to the base memory pointer.  This is
  172.                               the same value as was initially passed to routine
  173.                               'h4create'. 
  174.  
  175.                 mem_ref       The allocated memory chunk is placed on a double
  176.                               linked list just after the memory chunk specified by
  177.                               'mem_ref'.  If 'mem_ref' is '-1' a new double linked
  178.                               list is created.  Otherwise, 'mem_ref' must have
  179.                               previously been returned by 'h4get'. 
  180.  
  181. Returns         A memory reference number to the allocated memory chunk is
  182.                 returned.  This number can be zero or greater. 
  183.                
  184.                 A return of '(int) -1' means that no additional memory is
  185.                 available.  This error only occurs if 'u4error' has been
  186.                 modified to return on an out of memory error.
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193. h4remove()
  194.  
  195. Usage           int  h4remove( char ** ptr_ref_ptr, 
  196.                             int mem_ref ) 
  197.  
  198. Description     'h4remove' removes a memory chunk from its double linked list
  199.                 chain but does not free it. 
  200.  
  201.                 'h4remove' can be used in conjunction with 'h4add' to
  202.                 transfer a memory chunk from one linked list to another.  They
  203.                 can also be used to change the ordering of a linked list. 
  204.  
  205. Parameters      Name          Use 
  206.                
  207.                 ptr_ref_p     A pointer to the base memory pointer.  This is
  208.                               the same value as was initially passed to routine
  209.                               'h4create'. 
  210.  
  211.                 mem_ref       A reference integer to the memory chunk.  
  212.  
  213. Returns         Like 'h4free', the reference to the previous memory chunk is
  214.                 returned.  If a previous chunk does not exist, a reference
  215.                 integer to the next memory chunk will be returned.  If there is
  216.                 no next memory chunk, '(int) -1' is returned.
  217.  
  218.  
  219.  
  220. Memory Handling Example:
  221.  
  222.  
  223. void mem_test()
  224. {
  225.    struct test
  226.    {
  227.       int next, prev ;
  228.       char name[20] ;
  229.       char city[25] ;
  230.    } *test_ptr ;
  231.    
  232.    int chain_one, chain_two ;
  233.  
  234.    h4create( (char **) &test_ptr, 10,
  235.                sizeof(struct test), 5) ;
  236.  
  237.    /* Allocate a chunk for 'chain_one' */
  238.    chain_one =  h4get( &test_ptr, -1 ) ;
  239.  
  240.    /* Allocate another chunk for 'chain_one' */
  241.    chain_one =  h4get( &test_ptr, chain_one ) ;
  242.  
  243.    /* Assign some data */
  244.    strcpy( test_ptr[chain_one].name, "JACKSON" ) ;
  245.    strcpy( test_ptr[chain_one].city, "LONDON" ) ;
  246.  
  247.    /* Allocate a chunk for 'chain_two' */
  248.    chain_two =  h4get( &test_ptr, -1 ) ;
  249.  
  250.    /* Free the most recently allocated chunk of 'chain_one' */
  251.    chain_one =  h4free( &test_ptr, chain_one ) ;
  252. }
  253.