H5FSpkg.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * Programmer:  Quincey Koziol <koziol@ncsa.uiuc.edu>
00018  *              Tuesday, May  2, 2006
00019  *
00020  * Purpose:     This file contains declarations which are visible only within
00021  *              the H5FS package.  Source files outside the H5FS package should
00022  *              include H5FSprivate.h instead.
00023  */
00024 #ifndef H5FS_PACKAGE
00025 #error "Do not include this file outside the H5FS package!"
00026 #endif
00027 
00028 #ifndef _H5FSpkg_H
00029 #define _H5FSpkg_H
00030 
00031 /* Uncomment this macro to enable debugging output for free space manager */
00032 /* #define H5FS_DEBUG */
00033 
00034 /* Uncomment this macro to enable debugging output for free space sections */
00035 /* #define H5FS_SINFO_DEBUG */
00036 
00037 /* Uncomment this macro to enable extra sanity checking */
00038 /* #define H5FS_DEBUG_ASSERT */
00039 
00040 /* Get package's private header */
00041 #include "H5FSprivate.h"        /* File free space                      */
00042 
00043 /* Other private headers needed by this file */
00044 #include "H5ACprivate.h"        /* Metadata cache                       */
00045 #include "H5SLprivate.h"        /* Skip lists                           */
00046 
00047 /**************************/
00048 /* Package Private Macros */
00049 /**************************/
00050 
00051 /* Size of checksum information (on disk) */
00052 #define H5FS_SIZEOF_CHKSUM      4
00053 
00054 /* "Standard" size of prefix information for free space metadata */
00055 #define H5FS_METADATA_PREFIX_SIZE (                                           \
00056     H5_SIZEOF_MAGIC   /* Signature */                                         \
00057     + 1 /* Version */                                                         \
00058     + H5FS_SIZEOF_CHKSUM /* Metadata checksum */                              \
00059     )
00060 
00061 /* Size of the fractal heap header on disk */
00062 #define H5FS_HEADER_SIZE(f) (                                                 \
00063     /* General metadata fields */                                             \
00064     H5FS_METADATA_PREFIX_SIZE                                                 \
00065                                                                               \
00066     /* Free space header specific fields */                                   \
00067     + 1 /* Client ID */                                                       \
00068     + H5F_SIZEOF_SIZE(f) /* Total free space tracked */                       \
00069     + H5F_SIZEOF_SIZE(f) /* Total # of sections tracked */                    \
00070     + H5F_SIZEOF_SIZE(f) /* # of serializable sections tracked */             \
00071     + H5F_SIZEOF_SIZE(f) /* # of ghost sections tracked */                    \
00072     + 2 /* Number of section classes */                                       \
00073     + 2 /* Shrink percent */                                                  \
00074     + 2 /* Expand percent */                                                  \
00075     + 2 /* Size of address space for sections (log2 of value) */              \
00076     + H5F_SIZEOF_SIZE(f) /* Max. size of section to track */                  \
00077     + H5F_SIZEOF_ADDR(f) /* Address of serialized free space sections */      \
00078     + H5F_SIZEOF_SIZE(f) /* Size of serialized free space sections used */    \
00079     + H5F_SIZEOF_SIZE(f) /* Allocated size of serialized free space sections */ \
00080     )
00081 
00082 /* Size of the free space serialized sections on disk */
00083 #define H5FS_SINFO_PREFIX_SIZE(f) (                                           \
00084     /* General metadata fields */                                             \
00085     H5FS_METADATA_PREFIX_SIZE                                                 \
00086                                                                               \
00087     /* Free space serialized sections specific fields */                      \
00088     + H5F_SIZEOF_ADDR(f) /* Address of free space header for these sections */ \
00089     )
00090 
00091 
00092 /****************************/
00093 /* Package Private Typedefs */
00094 /****************************/
00095 
00096 /* Information for protecting a free space manager header */
00097 typedef struct H5FS_prot_t {
00098     size_t nclasses;                            /* Number of section classes */
00099     const H5FS_section_class_t **classes;       /* Array of section class info */
00100     void *cls_init_udata;                       /* Pointer to class init user data */
00101 } H5FS_prot_t;
00102 
00103 /* Free space section bin info */
00104 typedef struct H5FS_bin_t {
00105     size_t tot_sect_count;      /* Total # of sections in this bin */
00106     size_t serial_sect_count;   /* # of serializable sections in this bin */
00107     size_t ghost_sect_count;    /* # of un-serializable sections in this bin */
00108     H5SL_t *bin_list;           /* Skip list of differently sized sections */
00109 } H5FS_bin_t;
00110 
00111 /* Free space node for free space sections of the same size */
00112 typedef struct H5FS_node_t {
00113     hsize_t sect_size;          /* Size of all sections on list */
00114     size_t serial_count;        /* # of serializable sections on list */
00115     size_t ghost_count;         /* # of un-serializable sections on list */
00116     H5SL_t *sect_list;          /* Skip list to hold pointers to actual free list section node */
00117 } H5FS_node_t;
00118 
00119 /* Free space section info */
00120 typedef struct H5FS_sinfo_t {
00121     /* Information for H5AC cache functions, _must_ be first field in structure */
00122     H5AC_info_t cache_info;
00123 
00124 /* Stored information */
00125     H5FS_bin_t *bins;           /* Array of lists of lists of free sections   */
00126 
00127 /* Computed/cached values */
00128     hbool_t dirty;              /* Whether this info in memory is out of sync w/info in file */
00129     unsigned nbins;             /* Number of bins                             */
00130     size_t serial_size;         /* Total size of all serializable sections    */
00131     size_t tot_size_count;      /* Total number of differently sized sections */
00132     size_t serial_size_count;   /* Total number of differently sized serializable sections */
00133     size_t ghost_size_count;    /* Total number of differently sized un-serializable sections */
00134     unsigned sect_prefix_size;  /* Size of the section serialization prefix (in bytes) */
00135     unsigned sect_off_size;     /* Size of a section offset (in bytes)        */
00136     unsigned sect_len_size;     /* Size of a section length (in bytes)        */
00137     H5FS_t *fspace;             /* Pointer to free space manager that owns sections */
00138 
00139 /* Memory data structures (not stored directly) */
00140     H5SL_t *merge_list;         /* Skip list to hold sections for detecting merges */
00141 } H5FS_sinfo_t;
00142 
00143 /* Free space header info */
00144 struct H5FS_t {
00145     /* Information for H5AC cache functions, _must_ be first field in structure */
00146     H5AC_info_t cache_info;
00147 
00148 /* Stored information */
00149     /* Statistics about sections managed */
00150     hsize_t tot_space;          /* Total amount of space tracked              */
00151     hsize_t tot_sect_count;     /* Total # of sections tracked                */
00152     hsize_t serial_sect_count;  /* # of serializable sections tracked         */
00153     hsize_t ghost_sect_count;   /* # of un-serializable sections tracked      */
00154 
00155     /* Creation parameters */
00156     H5FS_client_t client;       /* Type of user of this free space manager    */
00157     unsigned nclasses;          /* Number of section classes handled          */
00158     unsigned shrink_percent;    /* Percent of "normal" serialized size to shrink serialized space at */
00159     unsigned expand_percent;    /* Percent of "normal" serialized size to expand serialized space at */
00160     unsigned max_sect_addr;     /* Size of address space free sections are within (log2 of actual value) */
00161     hsize_t max_sect_size;      /* Maximum size of section to track */
00162 
00163     /* Serialized section information */
00164     haddr_t sect_addr;          /* Address of the section info in the file    */
00165     hsize_t sect_size;          /* Size of the section info in the file       */
00166     hsize_t alloc_sect_size;    /* Allocated size of the section info in the file */
00167 
00168 /* Computed/cached values */
00169     unsigned rc;                /* Count of outstanding references to struct  */
00170     haddr_t addr;               /* Address of free space header on disk       */
00171     H5FS_sinfo_t *sinfo;        /* Section information                        */
00172     unsigned sinfo_lock_count;  /* # of times the section info has been locked */
00173     hbool_t sinfo_protected;    /* Whether the section info was protected when locked */
00174     hbool_t sinfo_modified;     /* Whether the section info has been modified while locked */
00175     H5AC_protect_t sinfo_accmode; /* Access mode for protecting the section info */
00176     size_t max_cls_serial_size; /* Max. additional size of serialized form of section */
00177     hsize_t    threshold;       /* Threshold for alignment              */
00178     hsize_t    alignment;       /* Alignment                            */
00179 
00180 
00181 /* Memory data structures (not stored directly) */
00182     H5FS_section_class_t *sect_cls; /* Array of section classes for this free list */
00183 };
00184 
00185 
00186 /*****************************/
00187 /* Package Private Variables */
00188 /*****************************/
00189 
00190 /* H5FS header inherits cache-like properties from H5AC */
00191 H5_DLLVAR const H5AC_class_t H5AC_FSPACE_HDR[1];
00192 
00193 /* H5FS section info inherits cache-like properties from H5AC */
00194 H5_DLLVAR const H5AC_class_t H5AC_FSPACE_SINFO[1];
00195 
00196 /* Declare a free list to manage the H5FS_node_t struct */
00197 H5FL_EXTERN(H5FS_node_t);
00198 
00199 /* Declare a free list to manage the H5FS_bin_t sequence information */
00200 H5FL_SEQ_EXTERN(H5FS_bin_t);
00201 
00202 /* Declare a free list to manage the H5FS_sinfo_t struct */
00203 H5FL_EXTERN(H5FS_sinfo_t);
00204 
00205 /* Declare a free list to manage the H5FS_t struct */
00206 H5FL_EXTERN(H5FS_t);
00207 
00208 
00209 /******************************/
00210 /* Package Private Prototypes */
00211 /******************************/
00212 
00213 /* Free space manager header routines */
00214 H5_DLL H5FS_t *H5FS_new(size_t nclasses, const H5FS_section_class_t *classes[],
00215     void *cls_init_udata);
00216 H5_DLL herr_t H5FS_incr(H5F_t *f, H5FS_t *fspace);
00217 H5_DLL herr_t H5FS_decr(H5F_t *f, H5FS_t *fspace);
00218 H5_DLL herr_t H5FS_dirty(H5F_t *f, H5FS_t *fspace);
00219 
00220 /* Free space section routines */
00221 H5_DLL H5FS_sinfo_t *H5FS_sinfo_new(H5F_t *f, H5FS_t *fspace);
00222 
00223 /* Metadata cache callbacks */
00224 H5_DLL herr_t H5FS_cache_hdr_dest(H5F_t *f, H5FS_t *hdr);
00225 H5_DLL herr_t H5FS_cache_sinfo_dest(H5F_t *f, H5FS_sinfo_t *sinfo);
00226 
00227 /* Sanity check routines */
00228 #ifdef H5FS_DEBUG
00229 H5_DLL herr_t H5FS_assert(const H5FS_t *fspace);
00230 H5_DLL herr_t H5FS_sect_assert(const H5FS_t *fspace);
00231 #endif /* H5FS_DEBUG */
00232 
00233 /* Testing routines */
00234 #ifdef H5FS_TESTING
00235 H5_DLL herr_t H5FS_get_cparam_test(const H5FS_t *fh, H5FS_create_t *cparam);
00236 H5_DLL int H5FS_cmp_cparam_test(const H5FS_create_t *cparam1, const H5FS_create_t *cparam2);
00237 #endif /* H5FS_TESTING */
00238 
00239 #endif /* _H5FSpkg_H */
00240