H5FSprivate.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  *
00018  * Created:             H5FSprivate.h
00019  *                      May  2 2006
00020  *                      Quincey Koziol <koziol@ncsa.uiuc.edu>
00021  *
00022  * Purpose:             Private header for library accessible file free space routines.
00023  *
00024  *-------------------------------------------------------------------------
00025  */
00026 
00027 #ifndef _H5FSprivate_H
00028 #define _H5FSprivate_H
00029 
00030 /* Include package's public header */
00031 #include "H5FSpublic.h"
00032 
00033 /* Private headers needed by this file */
00034 #include "H5Fprivate.h"         /* File access                          */
00035 #include "H5FLprivate.h"        /* Free Lists                           */
00036 
00037 /**************************/
00038 /* Library Private Macros */
00039 /**************************/
00040 
00041 /* Flags for H5FS_section_class_t 'flags' field */
00042 #define H5FS_CLS_GHOST_OBJ      0x01    /* Objects in this class shouldn't be
00043                                          *      serialized to the file.
00044                                          */
00045 #define H5FS_CLS_SEPAR_OBJ      0x02    /* Objects in this class shouldn't
00046                                          *      participate in merge operations.
00047                                          */
00048 #define H5FS_CLS_MERGE_SYM      0x04    /* Objects in this class only merge
00049                                          *      with other objects in this class.
00050                                          */
00051 #define H5FS_CLS_ADJUST_OK      0x08    /* Objects in this class can be merged
00052                                          *      without requiring a can_adjust/adjust
00053                                          *      callback pair.
00054                                          */
00055 
00056 /* Flags for H5FS_add() */
00057 #define H5FS_ADD_DESERIALIZING  0x01    /* Free space is being deserialized
00058                                          */
00059 #define H5FS_ADD_RETURNED_SPACE 0x02    /* Section was previously allocated
00060                                          *      and is being returned to the
00061                                          *      free space manager (usually
00062                                          *      as a result of freeing an
00063                                          *      object)
00064                                          */
00065 #define H5FS_ADD_SKIP_VALID     0x04    /* Don't check validity after adding
00066                                          *      this section.  (state of the
00067                                          *      managed sections is in flux)
00068                                          */
00069 
00070 /* Flags for deserialize callback  */
00071 #define H5FS_DESERIALIZE_NO_ADD  0x01   /* Don't add section to free space
00072                                          *      manager after it's deserialized
00073                                          *      (its only here for it's side-
00074                                          *      effects).
00075                                          */
00076 
00077 
00078 /****************************/
00079 /* Library Private Typedefs */
00080 /****************************/
00081 
00082 /* Free space info (forward decl - defined in H5FSpkg.h) */
00083 typedef struct H5FS_t H5FS_t;
00084 
00085 /* Forward declaration free space section info */
00086 typedef struct H5FS_section_info_t H5FS_section_info_t;
00087 
00088 /* Free space section class info */
00089 typedef struct H5FS_section_class_t {
00090     /* Class variables */
00091     const unsigned type;                /* Type of free space section */
00092     size_t serial_size;                 /* Size of serialized form of section */
00093     unsigned flags;                     /* Class flags */
00094     void *cls_private;                  /* Class private information */
00095 
00096     /* Class methods */
00097     herr_t (*init_cls)(struct H5FS_section_class_t *, void *);          /* Routine to initialize class-specific settings */
00098     herr_t (*term_cls)(struct H5FS_section_class_t *);                  /* Routine to terminate class-specific settings */
00099 
00100     /* Object methods */
00101     herr_t (*add)(H5FS_section_info_t *, unsigned *, void *);       /* Routine called when section is about to be added to manager */
00102     herr_t (*serialize)(const struct H5FS_section_class_t *, const H5FS_section_info_t *, uint8_t *);        /* Routine to serialize a "live" section into a buffer */
00103     H5FS_section_info_t *(*deserialize)(const struct H5FS_section_class_t *, hid_t dxpl_id, const uint8_t *, haddr_t, hsize_t, unsigned *);     /* Routine to deserialize a buffer into a "live" section */
00104     htri_t (*can_merge)(const H5FS_section_info_t *, const H5FS_section_info_t *, void *);  /* Routine to determine if two nodes are mergable */
00105     herr_t (*merge)(H5FS_section_info_t *, H5FS_section_info_t *, void *);      /* Routine to merge two nodes */
00106     htri_t (*can_shrink)(const H5FS_section_info_t *, void *);        /* Routine to determine if node can shrink container */
00107     herr_t (*shrink)(H5FS_section_info_t **, void *);   /* Routine to shrink container */
00108     herr_t (*free)(H5FS_section_info_t *);              /* Routine to free node */
00109     herr_t (*valid)(const struct H5FS_section_class_t *, const H5FS_section_info_t *);   /* Routine to check if a section is valid */
00110     H5FS_section_info_t *(*split)(H5FS_section_info_t *, hsize_t);     /* Routine to create the split section */
00111     herr_t (*debug)(const H5FS_section_info_t *, FILE *, int , int );   /* Routine to dump debugging information about a section */
00112 } H5FS_section_class_t;
00113 
00114 /* State of section ("live" or "serialized") */
00115 typedef enum H5FS_section_state_t {
00116     H5FS_SECT_LIVE,             /* Section has "live" memory references */
00117     H5FS_SECT_SERIALIZED        /* Section is in "serialized" form */
00118 } H5FS_section_state_t;
00119 
00120 /* Free space section info */
00121 struct H5FS_section_info_t {
00122     haddr_t     addr;                   /* Offset of free space section in the address space */
00123     hsize_t     size;                   /* Size of free space section */
00124     unsigned    type;                   /* Type of free space section (i.e. class) */
00125     H5FS_section_state_t state;         /* Whether the section is in "serialized" or "live" form */
00126 };
00127 
00128 /* Free space client IDs for identifying user of free space */
00129 typedef enum H5FS_client_t {
00130     H5FS_CLIENT_FHEAP_ID = 0,   /* Free space is used by fractal heap */
00131     H5FS_CLIENT_FILE_ID,        /* Free space is used by file */
00132     H5FS_NUM_CLIENT_ID          /* Number of free space client IDs (must be last)   */
00133 } H5FS_client_t;
00134 
00135 /* Free space creation parameters */
00136 typedef struct H5FS_create_t {
00137     H5FS_client_t client;               /* Client's ID */
00138     unsigned shrink_percent;            /* Percent of "normal" serialized size to shrink serialized space at */
00139     unsigned expand_percent;            /* Percent of "normal" serialized size to expand serialized space at */
00140     unsigned max_sect_addr;             /* Size of address space free sections are within (log2 of actual value) */
00141     hsize_t max_sect_size;              /* Maximum size of section to track */
00142 } H5FS_create_t;
00143 
00144 /* Free space statistics info */
00145 typedef struct H5FS_stat_t {
00146     hsize_t tot_space;          /* Total amount of space tracked              */
00147     hsize_t tot_sect_count;     /* Total # of sections tracked                */
00148     hsize_t serial_sect_count;  /* # of serializable sections tracked         */
00149     hsize_t ghost_sect_count;   /* # of un-serializable sections tracked      */
00150 } H5FS_stat_t;
00151 
00152 
00153 /* Typedef for iteration operations */
00154 typedef herr_t (*H5FS_operator_t)(const H5FS_section_info_t *sect,
00155         void *operator_data/*in,out*/);
00156 
00157 
00158 /*****************************/
00159 /* Library-private Variables */
00160 /*****************************/
00161 
00162 /* Declare a free list to manage the H5FS_section_class_t sequence information */
00163 H5FL_SEQ_EXTERN(H5FS_section_class_t);
00164 
00165 
00166 /***************************************/
00167 /* Library-private Function Prototypes */
00168 /***************************************/
00169 
00170 /* Free space manager routines */
00171 H5_DLL H5FS_t *H5FS_create(H5F_t *f, hid_t dxpl_id, haddr_t *fs_addr,
00172     const H5FS_create_t *fs_create, size_t nclasses,
00173     const H5FS_section_class_t *classes[], void *cls_init_udata, hsize_t alignment, hsize_t threshold);
00174 H5_DLL H5FS_t *H5FS_open(H5F_t *f, hid_t dxpl_id, haddr_t fs_addr,
00175     size_t nclasses, const H5FS_section_class_t *classes[], void *cls_init_udata, hsize_t alignment, hsize_t threshold);
00176 H5_DLL herr_t H5FS_size(const H5F_t *f, const H5FS_t *fspace, hsize_t *meta_size);
00177 H5_DLL herr_t H5FS_delete(H5F_t *f, hid_t dxpl_id, haddr_t fs_addr);
00178 H5_DLL herr_t H5FS_close(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace);
00179 
00180 /* Free space section routines */
00181 H5_DLL herr_t H5FS_sect_add(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace,
00182     H5FS_section_info_t *node, unsigned flags, void *op_data);
00183 H5_DLL herr_t H5FS_sect_try_extend(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace,
00184     haddr_t addr, hsize_t size, hsize_t extra_requested);
00185 H5_DLL herr_t H5FS_sect_remove(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace,
00186     H5FS_section_info_t *node);
00187 H5_DLL htri_t H5FS_sect_find(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace,
00188     hsize_t request, H5FS_section_info_t **node);
00189 H5_DLL herr_t H5FS_sect_iterate(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace, H5FS_operator_t op, void *op_data);
00190 H5_DLL herr_t H5FS_sect_stats(const H5FS_t *fspace, hsize_t *tot_space,
00191     hsize_t *nsects);
00192 H5_DLL herr_t H5FS_sect_change_class(H5F_t *f, hid_t dxpl_id, H5FS_t *fspace,
00193     H5FS_section_info_t *sect, unsigned new_class);
00194 
00195 /* Statistics routine */
00196 H5_DLL herr_t H5FS_stat_info(const H5FS_t *fh, H5FS_stat_t *stats);
00197 
00198 
00199 /* Debugging routines for dumping file structures */
00200 H5_DLL herr_t H5FS_debug(H5F_t *f, hid_t dxpl_id, haddr_t addr,
00201     FILE *stream, int indent, int fwidth);
00202 H5_DLL herr_t H5FS_sects_debug(H5F_t *f, hid_t dxpl_id, haddr_t addr,
00203     FILE *stream, int indent, int fwidth, haddr_t fs_addr, haddr_t client_addr);
00204 H5_DLL herr_t H5FS_sect_debug(const H5FS_t *fspace, const H5FS_section_info_t *sect,
00205     FILE *stream, int indent, int fwidth);
00206 
00207 #endif /* _H5FSprivate_H */
00208