home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / utils / gadtoolsbox / nofraglib / doc / nofrag.doc next >
Text File  |  1993-04-01  |  7KB  |  234 lines
  1.  
  2. TABLE OF CONTENTS
  3.  
  4. nofrag.library/GetMemoryChain
  5. nofrag.library/AllocItem
  6. nofrag.library/FreeItem
  7. nofrag.library/FreeMemoryChain
  8. nofrag.library/AllocVecItem
  9. nofrag.library/FreeVecItem
  10.  
  11.  
  12. nofrag.library/GetMemoryChain                  nofrag.library/GetMemoryChain
  13.  
  14.   NAME
  15.     GetMemoryChain -- allocate and initialize a MemoryChain.
  16.  
  17.   SYNOPSYS
  18.     chain = GetMemoryChain( blocksize )
  19.                             D0
  20.  
  21.     struct MemoryChain  *chain;
  22.     ULONG               blocksize;
  23.  
  24.   FUNCTION
  25.     This  routine will allocate the memory for the MemoryChain structure and
  26.     perform a  "NewList()" on  the "Blocks"  and  "Items" list fields of the
  27.     MemoryChain structure and it puts your blocksize value in the structure.
  28.     You should ALWAYS use  this routine to  obtain a MemoryChain  structure.
  29.     NOTE: ALL FIELDS IN THE MEMORYCHAIN STRUCTURE ARE PRIVATE AND SHOULD NOT
  30.           BE  CHANGED BY  ANYTHING ELSE THAN THE ROUTINES  SUPPLIED IN  THIS
  31.           LIBRARY.
  32.  
  33.   INPUTS
  34.     blocksize - A 32 bit  unsigned  integer  representing  the size  of  the
  35.                 memory it should allocate  for each MemoryBlock.
  36.  
  37.   RESULT
  38.     A pointer to the allocated and initialized MemoryChain structure or null
  39.     if the allocation failed.
  40.  
  41.   BUGS
  42.     None known.
  43.  
  44.   SEE ALSO
  45.     C.LIB/NewList()
  46.  
  47.  
  48. nofrag.library/AllocItem                            nofrag.library/AllocItem
  49.  
  50.   NAME
  51.     AllocItem -- allocate a chunk of memory from a MemoryChain.
  52.  
  53.   SYNOPSYS
  54.     memptr = AllocItem( chain, size, requirements )
  55.     D0                  A0     D0    D1
  56.  
  57.     void               *memptr;
  58.     struct MemoryChain *chain;
  59.     ULONG               size;
  60.     ULONG               requirements;
  61.  
  62.   FUNCTION
  63.     To scan the MemoryChain  to find a free  item which  is compatible  with
  64.     your requirements and size. If  it does  not find such an  item it  will
  65.     try to allocate a MemoryBlock. The allocation will  always be on a  long
  66.     word boundary and the allocated size is always rounded up to the nearest
  67.     possible multiple of eight. This is to  ensure  compatibility  with exec
  68.     it's "AllocMem()". Also the  memory allocated is  always cleared  wether
  69.     the MEMF_CLEAR bit was set or not.
  70.  
  71.   INPUTS
  72.     chain        - A pointer to the MemoryChain in which the allocation will
  73.                    take place.
  74.     size         - A 32 bit unsigned integer  which represents  the size  of
  75.                    the memory you require. This size may not be bigger  than
  76.                    the blocksize  you have  passed onto  "GetMemoryChain()".
  77.                    The size will always be padded to atleast "MINALLOC".
  78.     requirements - A 32  bit unsigned integer  which  represents the  memory
  79.                    type. (e.g. MEMF_CHIP, MEMF_PUBLIC....)
  80.  
  81.   RESULT
  82.     memptr = A  pointer to  the  allocated  memory or  NULL  if the  routine
  83.              failed. Although most call's will succeed you must always check
  84.              the return value.
  85.  
  86.   BUGS
  87.     None known.
  88.  
  89.   SEE ALSO
  90.     exec.library/AllocMem(), FreeItem(), GetMemoryChain()
  91.  
  92.  
  93. nofrag.library/FreeItem                              nofrag.library/FreeItem
  94.  
  95.   NAME
  96.     FreeItem -- free a chunk of memory in a MemoryChain.
  97.  
  98.   SYNOPSYS
  99.     FreeItem( chain, memptr, size )
  100.               A0     A1      D0
  101.  
  102.     struct MemoryChain *chain;
  103.     void               *memptr;
  104.     ULONG               size;
  105.  
  106.   FUNCTION
  107.     To  convert the passed memory pointer into a MemoryItem and  hang it  in
  108.     the MemoryChain it's free-items-list.  If the passed memory pointer  was
  109.     not allocated in the passed MemoryChain nothing is done to the memory.
  110.  
  111.   INPUTS
  112.     chain  - A pointer to the MemoryChain in which the memory was allocated.
  113.     memptr - A pointer to the previously allocated memory.
  114.     size   - A 32 bit  unsigned  integer which  represents  the size  of the
  115.              memory previously allocated.
  116.  
  117.   RESULT
  118.  
  119.   BUGS
  120.     The routine does not known if the  passed size is  actually the  same as
  121.     what was passed onto "AllocItem()". This MUST be the  same or the  chain
  122.     will be screwed up.
  123.  
  124.   SEE ALSO
  125.     AllocItem()
  126.  
  127.  
  128. nofrag.library/FreeMemoryChain                nofrag.library/FreeMemoryChain
  129.  
  130.   NAME
  131.     FreeMemoryChain -- free an entire MemoryChain.
  132.  
  133.   SYNOPSYS
  134.     FreeMemoryChain( chain, all )
  135.                      A0     D0
  136.  
  137.     struct MemoryChain *chain;
  138.     ULONG               all;
  139.  
  140.   FUNCTION
  141.     To call "FreeMem()" on all the MemoryBlocks still in the MemoryChain and
  142.     then call "FreeMem()" on the MemoryChain structure itself  if the  "all"
  143.     parameter specified TRUE.
  144.  
  145.   INPUTS
  146.     chain - A pointer to the MemoryChain you want to de-allocate.
  147.     all   - A boolean which should  read TRUE  if the MemoryChain  structure
  148.             itself has to be deallocated too and FALSE if not.
  149.  
  150.   RESULT
  151.     All memory the chain used is released and, if requested, the MemoryChain
  152.     has been deallocated too.
  153.  
  154.   BUGS
  155.     None known.
  156.  
  157.   SEE ALSO
  158.     exec.library/FreeMem(), GetMemoryChain()
  159.  
  160.  
  161. nofrag.library/AllocVecItem                       nofrag.library/FreeVecItem
  162.  
  163.   NAME
  164.     AllocVecItem -- allocate a chunk of memory from a MemoryChain.
  165.  
  166.   SYNOPSIS
  167.     memptr = AllocVecItem( chain, size, requirements )
  168.     D0                     A0     D0    D1
  169.  
  170.     void               *memptr;
  171.     struct MemoryChain *chain;
  172.     ULONG               size;
  173.     ULONG               requirements;
  174.  
  175.   FUNCTION
  176.     This does the same thing as  "AllocItem()"  with the exeption  that  the
  177.     size allocated will be remembered so "FreeVecItem()" knows the amount of
  178.     memory to mark as free. NOTE: You MUST deallocate  the memory  allocated
  179.     with this routine using "FreeVecItem()"!
  180.  
  181.   INPUTS
  182.     chain        - A pointer to the MemoryChain in which the allocation will
  183.                    take place.
  184.     size         - A 32 bit unsigned integer  which represents  the size  of
  185.                    the memory you require. This size may not be bigger  than
  186.                    the blocksize  you have  passed  onto  "GetMemoryChain()"
  187.                    minus four.
  188.                    The size will always be padded to atleast "MINALLOC".
  189.     requirements - A 32  bit unsigned integer  which  represents the  memory
  190.                    type. (e.g. MEMF_CHIP, MEMF_PUBLIC....)
  191.  
  192.   RESULT
  193.     memptr = A  pointer to  the  allocated  memory or  NULL  if the  routine
  194.              failed. Although most call's will succeed you must always check
  195.              the return value.
  196.  
  197.   BUGS
  198.     None known.
  199.  
  200.   SEE ALSO
  201.     exec.library/AllocMem(), FreeVecItem(), GetMemoryChain(), AllocItem()
  202.  
  203.  
  204. nofrag.library/FreeVecItem                        nofrag.library/FreeVecItem
  205.  
  206.   NAME
  207.     FreeVecItem -- free a chunk of memory in a MemoryChain.
  208.  
  209.   SYNOPSYS
  210.     FreeVecItem( chain, memptr )
  211.                  A0     A1
  212.  
  213.     struct MemoryChain *chain;
  214.     void               *memptr;
  215.  
  216.   FUNCTION
  217.     This frees a chunk of memory allocated with "AllocVecItem()".  You  must
  218.     NOT try to free a chunk of  memory  allocated  with "AllocItem()"  using
  219.     this routine or viceversa.
  220.  
  221.   INPUTS
  222.     chain  - A pointer to the MemoryChain in which the memory was allocated.
  223.     memptr - A pointer to the previously allocated memory.
  224.  
  225.   RESULT
  226.  
  227.   BUGS
  228.     None known.
  229.  
  230.   SEE ALSO
  231.     AllocItem(), AllocVecItem(), FreeItem(), exec.library/FreeMem()
  232.  
  233.  
  234.