home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / FREESPCE.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  12KB  |  262 lines
  1. /* @(#)Z 1.4 com/src/cm/FreeSpce.h, odstorage, od96os2, odos29646d 96/11/15 15:27:08 (96/10/29 09:18:26) */
  2. /*====START_GENERATED_PROLOG======================================
  3.  */
  4. /*
  5.  *   COMPONENT_NAME: odstorage
  6.  *
  7.  *   CLASSES: none
  8.  *
  9.  *   ORIGINS: 82,27
  10.  *
  11.  *
  12.  *   (C) COPYRIGHT International Business Machines Corp. 1995,1996
  13.  *   All Rights Reserved
  14.  *   Licensed Materials - Property of IBM
  15.  *   US Government Users Restricted Rights - Use, duplication or
  16.  *   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  17.  *       
  18.  *   IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  19.  *   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20.  *   PURPOSE. IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  21.  *   CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  22.  *   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  23.  *   OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
  24.  *   OR PERFORMANCE OF THIS SOFTWARE.
  25.  */
  26. /*====END_GENERATED_PROLOG========================================
  27.  */
  28.  
  29. /*
  30.     File:        FreeSpce.h 
  31.  
  32.     Contains:    Container Manager Free Space Value Management Interfaces
  33.  
  34.     Written by:    Ira L. Ruben
  35.  
  36.     Owned by:    Ed Lai
  37.  
  38.     Copyright:    ⌐ 1992-1994 by Apple Computer, Inc., all rights reserved.
  39.  
  40.     Change History (most recent first):
  41.  
  42.          <3>     12/9/94    EL        #1182275 Add cmRemoveSmallFreeSpace.
  43.          <2>     8/26/94    EL        #1182275 Add routines for handling the
  44.                                     temporary free list.
  45.          <2>      5/9/94    MB        #1162181: Changes necessary to install MMM.
  46.          <1>      2/3/94    EL        first checked in
  47.          <3>     1/19/94    EL        Add cmCopyTmpFreeToTOC to add temp free
  48.                                                     space to the permanent free space.
  49.          <2>      1/6/94    EL        Add cmTakeOverFreeList call to transfer the
  50.                                                     free list.
  51.  
  52.     To Do:
  53. */
  54.  
  55. /*---------------------------------------------------------------------------*
  56.  |                                                                           |
  57.  |                            <<< FreeSpce.h  >>>                            |
  58.  |                                                                           |
  59.  |         Container Manager Free Space Value Management Interfaces          |
  60.  |                                                                           |
  61.  |                               Ira L. Ruben                                |
  62.  |                                 4/23/92                                   |
  63.  |                                                                           |
  64.  |                    Copyright Apple Computer, Inc. 1992-1994               |
  65.  |                           All rights reserved.                            |
  66.  |                                                                           |
  67.  *---------------------------------------------------------------------------*
  68.  
  69.  This file contains interfaces for reusing deleted data space.  The routines record the
  70.  deleted space and reuse it for value data writes.
  71.  
  72.  The free space is maintained as a list of value segment entries for a "free space"
  73.  property belonging to the TOC ID 1 entry.  It is written to the container like other ID 1
  74.  properties to keep track of all the deleted space.
  75.  
  76.  If a container is opened for reusing free space, we use the free list to reuse the space.
  77. */
  78.  
  79.  
  80. #ifndef __FREESPACE__
  81. #define __FREESPACE__
  82.  
  83.  
  84. #ifndef __CMTYPES__
  85. #include "CMTypes.h"
  86. #endif
  87. #ifndef __CM_API_TYPES__
  88. #include "CMAPITyp.h"
  89. #endif
  90. #ifndef __TOCENTRIES__
  91. #include "TOCEnts.h"   
  92. #endif
  93. #ifndef __CONTAINEROPS__
  94. #include "Containr.h"  
  95. #endif
  96.  
  97.                                                                     CM_CFUNCTIONS
  98.  
  99. struct FreeSpaceItem {        /* this is used to store an item in the temporary free space */
  100.     ListLinks        theList;    /* Must be first entry. */
  101.     CM_ULONG        offset;        /* Offset into file. */
  102.     CM_ULONG        size;        /* Size of block to free. */
  103. };
  104. typedef struct FreeSpaceItem FreeSpaceItem;
  105.  
  106. void cmCopyTmpFreeToTOC(ContainerPtr container);
  107.     /*
  108.     This routine takes the temporary free space and merge it into the permanent free space.
  109.     */
  110.  
  111. void cmAddToFreeList(ContainerPtr container, TOCValuePtr theValueToFree,
  112.                                          CM_ULONG offset, CM_ULONG size);
  113.     /*
  114.     This routine is called whenever space for value data is to be freed.  The space is
  115.     recorded in a free list. The free list entries are maintained as value segments belonging
  116.     to the "free space" property of TOC object ID 1.
  117.     
  118.     The amount of space to be freed is specified in one of two possible ways:
  119.     
  120.          1. By passing a pointer to a value segment in theValueToFree.  The offset and size
  121.                 are extracted from the segment info.  If theValueToFree is for an immediate value,
  122.                 we simply exit since there is no container space to actually free.  Global names,
  123.                 as usual, are handled specially.  In particular, for no global names that have not
  124.                 yet been written to the container yet (we keep 'em in memory unto we write the TOC
  125.                 at container close time), then we ingore them just like immediates.  For "old"
  126.                 global names we do account for the space.
  127.                 
  128.          2. If theValueToFree is passed as NULL, then an explicit size and offset may be
  129.                 passed.  Note that a non-null theValueToFree has precedence over explicit offset
  130.                 and size.
  131.                 
  132.      As part of the freeing process, we scan the free list to see if the new space can be 
  133.      combined with an already existing entry.  It's a sort of on-the-fly garbage collector.
  134.      
  135.      For new containers, there is no "free space" property initially for ID 1.  It is created
  136.      here the first time we need to free space.  We remember the value header for the "free
  137.      space" property so that we may efficiently get at the list on all future calls.
  138.     */
  139.  
  140. void cmAddValueToTmpFreeList(TOCValueHdrPtr theValueHdr);
  141.     /*
  142.         This routine put all the free space used by a value into the temporary free list
  143.     */
  144.  
  145. void cmAddToTmpFreeList(ContainerPtr container, CM_ULONG offset, CM_ULONG size);
  146.     /*
  147.         This routine takes some free space and put it into the temporary free space property
  148.         for use in future.
  149.         
  150.         We want to put thing in the temporary free list for two reasons.
  151.         
  152.         For container opened for writing, we don't want to write into the old container
  153.         before we close it in case it crashes before it is closed, so we put it into
  154.         the temporary free list.
  155.         
  156.         For container opened for updating, we have free space that can be reused if
  157.         it is merged. Since we do not know whether we will just close the container
  158.         or merge it, we put it in the temporary free list and put it on the real
  159.         free list only if we do a merge at close time.
  160.     */
  161.  
  162.  
  163. void cmRemoveSmallFreeSpace(ContainerPtr container);
  164.  
  165.     /* 
  166.      There is certain overhead of storing a value segment. If a free space segment is so small
  167.      that the overhead of storing it is greater than the free space itself, then it is not
  168.      worth to keep the free space. So we go through the free space list and remove the small
  169.      segments.
  170.      
  171.      On the other hand, later we may free space that are are around these small segments.
  172.      So if we ignore these small segments, we may cause fragmentation of the free space
  173.      later. So we should revisit this issue to see if it is worthwhile to keep them anyway.
  174.     */
  175.  
  176. CM_ULONG cmGetFreeListEntry(ContainerPtr container, 
  177.                                                         CM_ULONG desiredSize, Boolean mustAllFit,
  178.                                                         CM_ULONG *actualSize);
  179.     /*
  180.     This routine returns one free list entry (if one exists).  The offset from that entry is
  181.     returned as the function result.  The size is returned in actualSize.  If there is no 
  182.     free space, or we can't find one big enough (see mustAllFit below), 0 is returned as the
  183.     function result and for the actualSize.  0's are also returned if the container was not
  184.     opened to reuse free space.
  185.     
  186.     The desiredSize is passed as what the caller would like as the single free list entry
  187.     amount, i.e., a "best fit".  It is also used when we find a bigger free list entry and
  188.     only have to reduce part of it.
  189.     
  190.     If mustAllFit is true, then we MUST find a single free list segment big enough or 0 will
  191.     be returned.  This is used for data that is not allowed to be continued with multiple
  192.     value segments (e.g., global names).
  193.     
  194.     The free list is built by cmAddToFreeList() as value segments belonging to a value header
  195.     of the "free space" property for TOC object ID 1.   If all the free list entries are
  196.     exhausted, the value header is freed along with the property.  If space is ever given up
  197.     after this through cmAddToFreeList(), it will recreate the "free space" property, its
  198.     value header, and the free list value entry segments.
  199.     */
  200.     
  201. void cmTakeOverFreeList(ContainerPtr toContainer, ContainerPtr container);    
  202.     /*--------------------------------------------------------------------------*
  203.      | cmTakeOverFreeList - have one container take the free space from another |
  204.      *--------------------------------------------------------------------------*
  205.      
  206.      When a target container is open by a container, we want to take over the
  207.      free space in the target container so that we can reuse the free space
  208.      in the target container. Since the target container is open read only, we
  209.      cannot update the free space list there. So the update container move the list
  210.      over so that it becomes the free list of the update container.
  211.      
  212.      This should only be done for one level, so the update container takes the
  213.      free list of the target container. Any free list that is in container that
  214.      is further down may be used already and should not be used.
  215.     */
  216.     
  217. CM_ULONG cmWriteData(TOCValueHdrPtr theValueHdr, CM_UCHAR *buffer, CM_ULONG size);
  218.     /*
  219.     This routine is the Container Manager's low-level value data writer.  It takes a value
  220.     header, and size bytes in the buffer and writes it to the container via the output
  221.     handler.  The amount written is returned.  If it is not equal to the passed size, the
  222.     caller should report an error.
  223.     
  224.     The reason this routine is used rather than using the CMfwrite() handler call directly is
  225.     that this routine checks to see if the container has been opened to reuse free space.  If
  226.     it hasn't, we degenerate into a simple CMfwrite() call.  If it has, then we use the free
  227.     list, built by cmAddToFreeList(), to write out the data segments to reuse the free space.
  228.     
  229.   In all cases the data written is recorded as value segments in the value list belonging
  230.   to the specified value header. The new segments are appended on to the END of the segment
  231.     list.  It is up to the caller to guarantee this is where the segments are to go.  The
  232.     continued flags are appropriately set.
  233.     
  234.     Note, as just mentioned, use this routine ONLY for appending data segments to a value.
  235.     Also, use this routine ONLY if continued segments are permitted for the data.  This means
  236.     you cannot call this routine to write global names.  They are always written as single
  237.     segments.
  238.     
  239.     Even with these restrictions, for the main case, i.e., CMWriteValueData(), this is not a
  240.     problem.  CMWriteValueData() is the primary caller.  It knows what it's doing with the
  241.     data (lets hope so).  So it knows when to call us here.
  242.     
  243.     The net effect is to reuse free space whenever we can if the container was opened for
  244.     updating, and to do straight CMfwrite() otherwise.
  245.     */
  246.  
  247.  
  248. void cmDeleteFreeSpace(ContainerPtr container, CM_ULONG beyondHere);
  249.     /*
  250.     This routine is called to remove all free list entries that have their space beyond the
  251.     specified offset, beyondHere.  All entries with starting offsets greater than or equal
  252.     to beyondHere are removed.  If one spans beyondHere it will be reduced appropriately.
  253.     
  254.     These entries are removed so so that we may overwrite from beyondHere with a new TOC.
  255.     Since we are reusing that space for the TOC we obviously can't keep free list entries for
  256.     it.
  257.     */
  258.     
  259.  
  260.                                                           CM_END_CFUNCTIONS
  261. #endif
  262.