H5Fpkg.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  *              Thursday, September 28, 2000
00019  *
00020  * Purpose:     This file contains declarations which are visible only within
00021  *              the H5F package.  Source files outside the H5F package should
00022  *              include H5Fprivate.h instead.
00023  */
00024 #ifndef H5F_PACKAGE
00025 #error "Do not include this file outside the H5F package!"
00026 #endif
00027 
00028 #ifndef _H5Fpkg_H
00029 #define _H5Fpkg_H
00030 
00031 /* Get package's private header */
00032 #include "H5Fprivate.h"
00033 
00034 /* Other public headers needed by this file */
00035 #include "H5Bpublic.h"          /* B-tree header, for H5B_NUM_BTREE_ID */
00036 
00037 /* Other private headers needed by this file */
00038 #include "H5private.h"          /* Generic Functions                    */
00039 #include "H5ACprivate.h"        /* Metadata cache                       */
00040 #include "H5FLprivate.h"        /* Free Lists                           */
00041 #include "H5FOprivate.h"        /* File objects                         */
00042 #include "H5FSprivate.h"        /* File free space                      */
00043 #include "H5Gprivate.h"         /* Groups                               */
00044 #include "H5Oprivate.h"         /* Object header messages               */
00045 #include "H5RCprivate.h"        /* Reference counted object functions   */
00046 
00047 
00048 /*
00049  * Feature: Define this constant on the compiler command-line if you want to
00050  *          see some debugging messages on the debug stream.
00051  */
00052 #ifdef NDEBUG
00053 #  undef H5F_DEBUG
00054 #endif
00055 
00056 /* Define the HDF5 file signature */
00057 #define H5F_SIGNATURE     "\211HDF\r\n\032\n"
00058 #define H5F_SIGNATURE_LEN 8
00059 
00060 /* Superblock status flags */
00061 #define H5F_SUPER_WRITE_ACCESS          0x01
00062 #define H5F_SUPER_FILE_OK               0x02
00063 #define H5F_SUPER_ALL_FLAGS             (H5F_SUPER_WRITE_ACCESS | H5F_SUPER_FILE_OK)
00064 
00065 /* Mask for removing private file access flags */
00066 #define H5F_ACC_PUBLIC_FLAGS            0x001fu
00067 
00068 /* Free space section+aggregator merge flags */
00069 #define H5F_FS_MERGE_METADATA           0x01    /* Section can merge with metadata aggregator */
00070 #define H5F_FS_MERGE_RAWDATA            0x02    /* Section can merge with small 'raw' data aggregator */
00071 
00072 /* Macro to abstract checking whether file is using a free space manager */
00073 #define H5F_HAVE_FREE_SPACE_MANAGER(F)  TRUE    /* Currently always have a free space manager */
00074 
00075 /* Macros for encoding/decoding superblock */
00076 #define H5F_MAX_DRVINFOBLOCK_SIZE  1024         /* Maximum size of superblock driver info buffer */
00077 #define H5F_DRVINFOBLOCK_HDR_SIZE 16            /* Size of superblock driver info header */
00078 
00079 /* Superblock sizes for various versions */
00080 #define H5F_SIZEOF_CHKSUM 4     /* Checksum size in the file */
00081 
00082 /* Fixed-size portion at the beginning of all superblocks */
00083 #define H5F_SUPERBLOCK_FIXED_SIZE ( H5F_SIGNATURE_LEN                   \
00084         + 1) /* superblock version */
00085 
00086 /* Macros for computing variable-size superblock size */
00087 #define H5F_SUPERBLOCK_VARLEN_SIZE_COMMON                               \
00088         (2  /* freespace, and root group versions */                    \
00089         + 1 /* reserved */                                              \
00090         + 3 /* shared header vers, size of address, size of lengths */  \
00091         + 1 /* reserved */                                              \
00092         + 4 /* group leaf k, group internal k */                        \
00093         + 4) /* consistency flags */
00094 #define H5F_SUPERBLOCK_VARLEN_SIZE_V0(f)                                \
00095         ( H5F_SUPERBLOCK_VARLEN_SIZE_COMMON /* Common variable-length info */ \
00096         + H5F_SIZEOF_ADDR(f) /* base address */                         \
00097         + H5F_SIZEOF_ADDR(f) /* <unused> */                             \
00098         + H5F_SIZEOF_ADDR(f) /* EOF address */                          \
00099         + H5F_SIZEOF_ADDR(f) /* driver block address */                 \
00100         + H5G_SIZEOF_ENTRY(f)) /* root group ptr */
00101 #define H5F_SUPERBLOCK_VARLEN_SIZE_V1(f)                                \
00102         ( H5F_SUPERBLOCK_VARLEN_SIZE_COMMON /* Common variable-length info */ \
00103         + 2 /* indexed B-tree internal k */                             \
00104         + 2 /* reserved */                                              \
00105         + H5F_SIZEOF_ADDR(f) /* base address */                         \
00106         + H5F_SIZEOF_ADDR(f) /* <unused> */                             \
00107         + H5F_SIZEOF_ADDR(f) /* EOF address */                          \
00108         + H5F_SIZEOF_ADDR(f) /* driver block address */                 \
00109         + H5G_SIZEOF_ENTRY(f)) /* root group ptr */
00110 #define H5F_SUPERBLOCK_VARLEN_SIZE_V2(f)                                \
00111         ( 2 /* size of address, size of lengths */                      \
00112         + 1 /* consistency flags */                                     \
00113         + H5F_SIZEOF_ADDR(f) /* base address */                         \
00114         + H5F_SIZEOF_ADDR(f) /* superblock extension address */         \
00115         + H5F_SIZEOF_ADDR(f) /* EOF address */                          \
00116         + H5F_SIZEOF_ADDR(f) /* root group object header address */     \
00117         + H5F_SIZEOF_CHKSUM) /* superblock checksum (keep this last) */
00118 #define H5F_SUPERBLOCK_VARLEN_SIZE(v, f) (                              \
00119         (v == 0 ? H5F_SUPERBLOCK_VARLEN_SIZE_V0(f) : 0)                 \
00120         + (v == 1 ? H5F_SUPERBLOCK_VARLEN_SIZE_V1(f) : 0)               \
00121         + (v == 2 ? H5F_SUPERBLOCK_VARLEN_SIZE_V2(f) : 0))
00122 
00123 /* Total size of superblock, depends on superblock version */
00124 #define H5F_SUPERBLOCK_SIZE(v, f) ( H5F_SUPERBLOCK_FIXED_SIZE           \
00125         + H5F_SUPERBLOCK_VARLEN_SIZE(v, f))
00126 
00127 
00128 /* Structure for metadata & "small [raw] data" block aggregation fields */
00129 struct H5F_blk_aggr_t {
00130     unsigned long       feature_flag;   /* Feature flag type */
00131     hsize_t             alloc_size;     /* Size for allocating new blocks */
00132     hsize_t             tot_size;       /* Total amount of bytes aggregated into block */
00133     hsize_t             size;           /* Current size of block left */
00134     haddr_t             addr;           /* Location of block left */
00135 };
00136 
00137 /* Structure for metadata accumulator fields */
00138 typedef struct H5F_meta_accum_t {
00139     unsigned char      *buf;            /* Buffer to hold the accumulated metadata */
00140     haddr_t             loc;            /* File location (offset) of the accumulated metadata */
00141     size_t              size;           /* Size of the accumulated metadata buffer used (in bytes) */
00142     size_t              alloc_size;     /* Size of the accumulated metadata buffer allocated (in bytes) */
00143     hbool_t             dirty;          /* Flag to indicate that the accumulated metadata is dirty */
00144 } H5F_meta_accum_t;
00145 
00146 /* Enum for free space manager state */
00147 typedef enum H5F_fs_state_t {
00148     H5F_FS_STATE_CLOSED,                /* Free space manager is closed */
00149     H5F_FS_STATE_OPEN,                  /* Free space manager has been opened */
00150     H5F_FS_STATE_DELETING               /* Free space manager is being deleted */
00151 } H5F_fs_state_t;
00152 
00153 /* A record of the mount table */
00154 typedef struct H5F_mount_t {
00155     struct H5G_t        *group; /* Mount point group held open          */
00156     struct H5F_t        *file;  /* File mounted at that point           */
00157 } H5F_mount_t;
00158 
00159 /*
00160  * The mount table describes what files are attached to (mounted on) the file
00161  * to which this table belongs.
00162  */
00163 typedef struct H5F_mtab_t {
00164     unsigned            nmounts;/* Number of children which are mounted */
00165     unsigned            nalloc; /* Number of mount slots allocated      */
00166     H5F_mount_t         *child; /* An array of mount records            */
00167 } H5F_mtab_t;
00168 
00169 /* Structure specifically to store superblock. This was originally
00170  * maintained entirely within H5F_file_t, but is now extracted
00171  * here because the superblock is now handled by the cache */
00172 typedef struct H5F_super_t {
00173     H5AC_info_t cache_info;     /* Cache entry information structure          */
00174     unsigned    super_vers;     /* Superblock version                         */
00175     uint8_t     status_flags;   /* File status flags                          */
00176     unsigned    sym_leaf_k;     /* Size of leaves in symbol tables            */
00177     unsigned    btree_k[H5B_NUM_BTREE_ID]; /* B-tree key values for each type */
00178     haddr_t     base_addr;      /* Absolute base address for rel.addrs.       */
00179                                 /* (superblock for file is at this offset)    */
00180     haddr_t     ext_addr;       /* Relative address of superblock extension   */
00181     haddr_t     driver_addr;    /* File driver information block address      */
00182     haddr_t     root_addr;      /* Root group address                         */
00183     H5G_entry_t *root_ent;      /* Root group symbol table entry              */
00184 } H5F_super_t;
00185 
00186 /*
00187  * Define the structure to store the file information for HDF5 files. One of
00188  * these structures is allocated per file, not per H5Fopen(). That is, set of
00189  * H5F_t structs can all point to the same H5F_file_t struct. The `nrefs'
00190  * count in this struct indicates the number of H5F_t structs which are
00191  * pointing to this struct.
00192  */
00193 typedef struct H5F_file_t {
00194     H5FD_t      *lf;            /* Lower level file handle for I/O      */
00195     H5F_super_t *sblock;        /* Pointer to (pinned) superblock for file */
00196     unsigned    nrefs;          /* Ref count for times file is opened   */
00197     unsigned    flags;          /* Access Permissions for file          */
00198     H5F_mtab_t  mtab;           /* File mount table                     */
00199 
00200     /* Cached values from FCPL/superblock */
00201     uint8_t     sizeof_addr;    /* Size of addresses in file            */
00202     uint8_t     sizeof_size;    /* Size of offsets in file              */
00203     haddr_t     sohm_addr;      /* Relative address of shared object header message table */
00204     unsigned    sohm_vers;      /* Version of shared message table on disk */
00205     unsigned    sohm_nindexes;  /* Number of shared messages indexes in the table */
00206     unsigned long feature_flags; /* VFL Driver feature Flags            */
00207     haddr_t     maxaddr;        /* Maximum address for file             */
00208 
00209     H5AC_t      *cache;         /* The object cache                     */
00210     H5AC_cache_config_t
00211                 mdc_initCacheCfg; /* initial configuration for the      */
00212                                 /* metadata cache.  This structure is   */
00213                                 /* fixed at creation time and should    */
00214                                 /* not change thereafter.               */
00215     hid_t       fcpl_id;        /* File creation property list ID       */
00216     H5F_close_degree_t fc_degree;   /* File close behavior degree       */
00217     size_t      rdcc_nslots;    /* Size of raw data chunk cache (slots) */
00218     size_t      rdcc_nbytes;    /* Size of raw data chunk cache (bytes) */
00219     double      rdcc_w0;        /* Preempt read chunks first? [0.0..1.0]*/
00220     size_t      sieve_buf_size; /* Size of the data sieve buffer allocated (in bytes) */
00221     hsize_t     threshold;      /* Threshold for alignment              */
00222     hsize_t     alignment;      /* Alignment                            */
00223     unsigned    gc_ref;         /* Garbage-collect references?          */
00224     hbool_t     latest_format;  /* Always use the latest format?        */
00225     hbool_t     store_msg_crt_idx;  /* Store creation index for object header messages? */
00226     int         ncwfs;          /* Num entries on cwfs list             */
00227     struct H5HG_heap_t **cwfs;  /* Global heap cache                    */
00228     struct H5G_t *root_grp;     /* Open root group                      */
00229     H5FO_t *open_objs;          /* Open objects in file                 */
00230     H5RC_t *grp_btree_shared;   /* Ref-counted group B-tree node info   */
00231 
00232     /* File space allocation information */
00233     hbool_t     use_tmp_space;  /* Whether temp. file space allocation is allowed */
00234     haddr_t     tmp_addr;       /* Next address to use for temp. space in the file */
00235     unsigned fs_aggr_merge[H5FD_MEM_NTYPES];    /* Flags for whether free space can merge with aggregator(s) */
00236     H5F_fs_state_t fs_state[H5FD_MEM_NTYPES];   /* State of free space manager for each type */
00237     haddr_t fs_addr[H5FD_MEM_NTYPES];   /* Address of free space manager info for each type */
00238     H5FS_t *fs_man[H5FD_MEM_NTYPES];    /* Free space manager for each file space type */
00239     H5FD_mem_t fs_type_map[H5FD_MEM_NTYPES]; /* Mapping of "real" file space type into tracked type */
00240     H5F_blk_aggr_t meta_aggr;   /* Metadata aggregation info */
00241                                 /* (if aggregating metadata allocations) */
00242     H5F_blk_aggr_t sdata_aggr;  /* "Small data" aggregation info */
00243                                 /* (if aggregating "small data" allocations) */
00244 
00245     /* Metadata accumulator information */
00246     H5F_meta_accum_t accum;     /* Metadata accumulator info            */
00247 } H5F_file_t;
00248 
00249 /*
00250  * This is the top-level file descriptor.  One of these structures is
00251  * allocated every time H5Fopen() is called although they may contain pointers
00252  * to shared H5F_file_t structs.
00253  */
00254 struct H5F_t {
00255     unsigned            intent;         /* The flags passed to H5F_open()*/
00256     char                *open_name;     /* Name used to open file       */
00257     char                *actual_name;   /* Actual name of the file, after resolving symlinks, etc. */
00258     char                *extpath;       /* Path for searching target external link file */
00259     H5F_file_t          *shared;        /* The shared file info         */
00260     unsigned            nopen_objs;     /* Number of open object headers*/
00261     H5FO_t              *obj_count;     /* # of time each object is opened through top file structure */
00262     hid_t               file_id;        /* ID of this file              */
00263     hbool_t             closing;        /* File is in the process of being closed */
00264     struct H5F_t        *parent;        /* Parent file that this file is mounted to */
00265     unsigned            nmounts;        /* Number of children mounted to this file */
00266 };
00267 
00268 
00269 /*****************************/
00270 /* Package Private Variables */
00271 /*****************************/
00272 
00273 /* Declare a free list to manage the H5F_t struct */
00274 H5FL_EXTERN(H5F_t);
00275 
00276 /* Declare a free list to manage the H5F_file_t struct */
00277 H5FL_EXTERN(H5F_file_t);
00278 
00279 H5_DLLVAR const H5AC_class_t H5AC_SUPERBLOCK[1];
00280 
00281 
00282 /******************************/
00283 /* Package Private Prototypes */
00284 /******************************/
00285 
00286 /* General routines */
00287 H5_DLL herr_t H5F_init(void);
00288 H5_DLL haddr_t H5F_locate_signature(H5FD_t *file, hid_t dxpl_id);
00289 H5_DLL herr_t H5F_flush(H5F_t *f, hid_t dxpl_id);
00290 
00291 /* File mount related routines */
00292 H5_DLL herr_t H5F_close_mounts(H5F_t *f);
00293 H5_DLL int H5F_term_unmount_cb(void *obj_ptr, hid_t obj_id, void *key);
00294 H5_DLL herr_t H5F_mount_count_ids(H5F_t *f, unsigned *nopen_files, unsigned *nopen_objs);
00295 H5_DLL herr_t H5F_flush_mounts(H5F_t *f, hid_t dxpl_id);
00296 
00297 /* Superblock related routines */
00298 H5_DLL herr_t H5F_super_init(H5F_t *f, hid_t dxpl_id);
00299 H5_DLL herr_t H5F_super_read(H5F_t *f, hid_t dxpl_id);
00300 H5_DLL herr_t H5F_super_size(H5F_t *f, hid_t dxpl_id, hsize_t *super_size,
00301     hsize_t *super_ext_info);
00302 
00303 /* Superblock extension related routines */
00304 H5_DLL herr_t H5F_super_ext_open(H5F_t *f, haddr_t ext_addr, H5O_loc_t *ext_ptr);
00305 H5_DLL herr_t H5F_super_ext_write_msg(H5F_t *f, hid_t dxpl_id, void *mesg, unsigned id, hbool_t may_create);
00306 H5_DLL herr_t H5F_super_ext_close(H5F_t *f, H5O_loc_t *ext_ptr);
00307 
00308 /* Metadata accumulator routines */
00309 H5_DLL htri_t H5F_accum_read(const H5F_t *f, hid_t dxpl_id, H5FD_mem_t type,
00310     haddr_t addr, size_t size, void *buf);
00311 H5_DLL htri_t H5F_accum_write(const H5F_t *f, hid_t dxpl_id, H5FD_mem_t type,
00312     haddr_t addr, size_t size, const void *buf);
00313 H5_DLL herr_t H5F_accum_free(H5F_t *f, hid_t dxpl_id, H5FD_mem_t type,
00314     haddr_t addr, hsize_t size);
00315 H5_DLL herr_t H5F_accum_flush(H5F_t *f, hid_t dxpl_id);
00316 H5_DLL herr_t H5F_accum_reset(H5F_t *f, hid_t dxpl_id);
00317 
00318 /* Shared file list related routines */
00319 H5_DLL herr_t H5F_sfile_add(H5F_file_t *shared);
00320 H5_DLL H5F_file_t * H5F_sfile_search(H5FD_t *lf);
00321 H5_DLL herr_t H5F_sfile_remove(H5F_file_t *shared);
00322 
00323 /* Testing functions */
00324 #ifdef H5F_TESTING
00325 H5_DLL herr_t H5F_get_sohm_mesg_count_test(hid_t fid, unsigned type_id,
00326     size_t *mesg_count);
00327 H5_DLL herr_t H5F_check_cached_stab_test(hid_t file_id);
00328 H5_DLL herr_t H5F_get_maxaddr_test(hid_t file_id, haddr_t *maxaddr);
00329 #endif /* H5F_TESTING */
00330 
00331 #endif /* _H5Fpkg_H */
00332