H5FDpublic.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:  Robb Matzke <matzke@llnl.gov>
00018  *              Monday, July 26, 1999
00019  */
00020 #ifndef _H5FDpublic_H
00021 #define _H5FDpublic_H
00022 
00023 #include "H5public.h"
00024 #include "H5Fpublic.h"          /*for H5F_close_degree_t */
00025 
00026 #define H5_HAVE_VFL 1 /*define a convenient app feature test*/
00027 #define H5FD_VFD_DEFAULT 0   /* Default VFL driver value */
00028 
00029 /* Types of allocation requests: see H5Fpublic.h  */
00030 typedef enum H5F_mem_t  H5FD_mem_t;
00031 
00032 /* Map "fractal heap" header blocks to 'ohdr' type file memory, since its
00033  * a fair amount of work to add a new kind of file memory and they are similar
00034  * enough to object headers and probably too minor to deserve their own type.
00035  *
00036  * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they
00037  * are similar to fractal heap header blocks.
00038  *
00039  * Map "fractal heap" direct blocks to 'lheap' type file memory, since they
00040  * will be replacing local heaps.
00041  *
00042  * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they
00043  * represent large objects that are directly stored in the file.
00044  *
00045  *      -QAK
00046  */
00047 #define H5FD_MEM_FHEAP_HDR      H5FD_MEM_OHDR
00048 #define H5FD_MEM_FHEAP_IBLOCK   H5FD_MEM_OHDR
00049 #define H5FD_MEM_FHEAP_DBLOCK   H5FD_MEM_LHEAP
00050 #define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW
00051 
00052 /* Map "free space" header blocks to 'ohdr' type file memory, since its
00053  * a fair amount of work to add a new kind of file memory and they are similar
00054  * enough to object headers and probably too minor to deserve their own type.
00055  *
00056  * Map "free space" serialized sections to 'lheap' type file memory, since they
00057  * are similar enough to local heap info.
00058  *
00059  *      -QAK
00060  */
00061 #define H5FD_MEM_FSPACE_HDR     H5FD_MEM_OHDR
00062 #define H5FD_MEM_FSPACE_SINFO   H5FD_MEM_LHEAP
00063 
00064 /* Map "shared object header message" master table to 'ohdr' type file memory,
00065  * since its a fair amount of work to add a new kind of file memory and they are
00066  * similar enough to object headers and probably too minor to deserve their own
00067  * type.
00068  *
00069  * Map "shared object header message" indices to 'btree' type file memory,
00070  * since they are similar enough to B-tree nodes.
00071  *
00072  *      -QAK
00073  */
00074 #define H5FD_MEM_SOHM_TABLE     H5FD_MEM_OHDR
00075 #define H5FD_MEM_SOHM_INDEX     H5FD_MEM_BTREE
00076 
00077 /*
00078  * A free-list map which maps all types of allocation requests to a single
00079  * free list.  This is useful for drivers that don't really care about
00080  * keeping different requests segregated in the underlying file and which
00081  * want to make most efficient reuse of freed memory.  The use of the
00082  * H5FD_MEM_SUPER free list is arbitrary.
00083  */
00084 #define H5FD_FLMAP_SINGLE {                                                   \
00085     H5FD_MEM_SUPER,                     /*default*/                           \
00086     H5FD_MEM_SUPER,                     /*super*/                             \
00087     H5FD_MEM_SUPER,                     /*btree*/                             \
00088     H5FD_MEM_SUPER,                     /*draw*/                              \
00089     H5FD_MEM_SUPER,                     /*gheap*/                             \
00090     H5FD_MEM_SUPER,                     /*lheap*/                             \
00091     H5FD_MEM_SUPER                      /*ohdr*/                              \
00092 }
00093 
00094 /*
00095  * A free-list map which segregates requests into `raw' or `meta' data
00096  * pools.
00097  */
00098 #define H5FD_FLMAP_DICHOTOMY {                                                \
00099     H5FD_MEM_SUPER,                     /*default*/                           \
00100     H5FD_MEM_SUPER,                     /*super*/                             \
00101     H5FD_MEM_SUPER,                     /*btree*/                             \
00102     H5FD_MEM_DRAW,                      /*draw*/                              \
00103     H5FD_MEM_SUPER,                     /*gheap*/                             \
00104     H5FD_MEM_SUPER,                     /*lheap*/                             \
00105     H5FD_MEM_SUPER                      /*ohdr*/                              \
00106 }
00107 
00108 /*
00109  * The default free list map which causes each request type to use it's own
00110  * free-list.
00111  */
00112 #define H5FD_FLMAP_DEFAULT {                                                  \
00113     H5FD_MEM_DEFAULT,                   /*default*/                           \
00114     H5FD_MEM_DEFAULT,                   /*super*/                             \
00115     H5FD_MEM_DEFAULT,                   /*btree*/                             \
00116     H5FD_MEM_DEFAULT,                   /*draw*/                              \
00117     H5FD_MEM_DEFAULT,                   /*gheap*/                             \
00118     H5FD_MEM_DEFAULT,                   /*lheap*/                             \
00119     H5FD_MEM_DEFAULT                    /*ohdr*/                              \
00120 }
00121 
00122 
00123 /* Define VFL driver features that can be enabled on a per-driver basis */
00124 /* These are returned with the 'query' function pointer in H5FD_class_t */
00125     /*
00126      * Defining the H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that
00127      * the library will attempt to allocate a larger block for metadata and
00128      * then sub-allocate each metadata request from that larger block.
00129      */
00130 #define H5FD_FEAT_AGGREGATE_METADATA    0x00000001
00131     /*
00132      * Defining the H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that
00133      * the library will attempt to cache metadata as it is written to the file
00134      * and build up a larger block of metadata to eventually pass to the VFL
00135      * 'write' routine.
00136      *
00137      * Distinguish between updating the metadata accumulator on writes and
00138      * reads.  This is particularly (perhaps only, even) important for MPI-I/O
00139      * where we guarantee that writes are collective, but reads may not be.
00140      * If we were to allow the metadata accumulator to be written during a
00141      * read operation, the application would hang.
00142      */
00143 #define H5FD_FEAT_ACCUMULATE_METADATA_WRITE     0x00000002
00144 #define H5FD_FEAT_ACCUMULATE_METADATA_READ      0x00000004
00145 #define H5FD_FEAT_ACCUMULATE_METADATA   (H5FD_FEAT_ACCUMULATE_METADATA_WRITE|H5FD_FEAT_ACCUMULATE_METADATA_READ)
00146     /*
00147      * Defining the H5FD_FEAT_DATA_SIEVE for a VFL driver means that
00148      * the library will attempt to cache raw data as it is read from/written to
00149      * a file in a "data seive" buffer.  See Rajeev Thakur's papers:
00150      *  http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz
00151      *  http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz
00152      */
00153 #define H5FD_FEAT_DATA_SIEVE            0x00000008
00154     /*
00155      * Defining the H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that
00156      * the library will attempt to allocate a larger block for "small" raw data
00157      * and then sub-allocate "small" raw data requests from that larger block.
00158      */
00159 #define H5FD_FEAT_AGGREGATE_SMALLDATA   0x00000010
00160     /*
00161      * Defining the H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that
00162      * the library will ignore the driver info that is encoded in the file
00163      * for the VFL driver.  (This will cause the driver info to be eliminated
00164      * from the file when it is flushed/closed, if the file is opened R/W).
00165      */
00166 #define H5FD_FEAT_IGNORE_DRVRINFO       0x00000020
00167     /*
00168      * Defining the H5FD_FEAT_DIRTY_SBLK_LOAD for a VFL driver means that
00169      * the library will mark the superblock dirty when the file is opened
00170      * R/W.  This will cause the driver info to be re-encoded when the file
00171      * is flushed/closed.
00172      */
00173 #define H5FD_FEAT_DIRTY_SBLK_LOAD       0x00000040
00174     /*
00175      * Defining the H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that
00176      * the handle for the VFD (returned with the 'get_handle' callback) is
00177      * of type 'int' and is compatible with POSIX I/O calls.
00178      */
00179 #define H5FD_FEAT_POSIX_COMPAT_HANDLE   0x00000080
00180 
00181 
00182 /* Forward declaration */
00183 typedef struct H5FD_t H5FD_t;
00184 
00185 /* Class information for each file driver */
00186 typedef struct H5FD_class_t {
00187     const char *name;
00188     haddr_t maxaddr;
00189     H5F_close_degree_t fc_degree;
00190     hsize_t (*sb_size)(H5FD_t *file);
00191     herr_t  (*sb_encode)(H5FD_t *file, char *name/*out*/,
00192                          unsigned char *p/*out*/);
00193     herr_t  (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p);
00194     size_t  fapl_size;
00195     void *  (*fapl_get)(H5FD_t *file);
00196     void *  (*fapl_copy)(const void *fapl);
00197     herr_t  (*fapl_free)(void *fapl);
00198     size_t  dxpl_size;
00199     void *  (*dxpl_copy)(const void *dxpl);
00200     herr_t  (*dxpl_free)(void *dxpl);
00201     H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl,
00202                     haddr_t maxaddr);
00203     herr_t  (*close)(H5FD_t *file);
00204     int     (*cmp)(const H5FD_t *f1, const H5FD_t *f2);
00205     herr_t  (*query)(const H5FD_t *f1, unsigned long *flags);
00206     herr_t  (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map);
00207     haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
00208     herr_t  (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
00209                     haddr_t addr, hsize_t size);
00210     haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type);
00211     herr_t  (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr);
00212     haddr_t (*get_eof)(const H5FD_t *file);
00213     herr_t  (*get_handle)(H5FD_t *file, hid_t fapl, void**file_handle);
00214     herr_t  (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl,
00215                     haddr_t addr, size_t size, void *buffer);
00216     herr_t  (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl,
00217                      haddr_t addr, size_t size, const void *buffer);
00218     herr_t  (*flush)(H5FD_t *file, hid_t dxpl_id, unsigned closing);
00219     herr_t  (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
00220     herr_t  (*lock)(H5FD_t *file, unsigned char *oid, unsigned lock_type, hbool_t last);
00221     herr_t  (*unlock)(H5FD_t *file, unsigned char *oid, hbool_t last);
00222     H5FD_mem_t fl_map[H5FD_MEM_NTYPES];
00223 } H5FD_class_t;
00224 
00225 /* A free list is a singly-linked list of address/size pairs. */
00226 typedef struct H5FD_free_t {
00227     haddr_t             addr;
00228     hsize_t             size;
00229     struct H5FD_free_t  *next;
00230 } H5FD_free_t;
00231 
00232 /*
00233  * The main datatype for each driver. Public fields common to all drivers
00234  * are declared here and the driver appends private fields in memory.
00235  */
00236 struct H5FD_t {
00237     hid_t               driver_id;      /*driver ID for this file   */
00238     const H5FD_class_t *cls;            /*constant class info       */
00239     unsigned long       fileno;         /* File 'serial' number     */
00240     unsigned long       feature_flags;  /* VFL Driver feature Flags */
00241     haddr_t             maxaddr;        /* For this file, overrides class */
00242     haddr_t             base_addr;      /* Base address for HDF5 data w/in file */
00243 
00244     /* Space allocation management fields */
00245     hsize_t             threshold;      /* Threshold for alignment  */
00246     hsize_t             alignment;      /* Allocation alignment     */
00247 };
00248 
00249 #ifdef __cplusplus
00250 extern "C" {
00251 #endif
00252 
00253 /* Function prototypes */
00254 H5_DLL hid_t H5FDregister(const H5FD_class_t *cls);
00255 H5_DLL herr_t H5FDunregister(hid_t driver_id);
00256 H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id,
00257                         haddr_t maxaddr);
00258 H5_DLL herr_t H5FDclose(H5FD_t *file);
00259 H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2);
00260 H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags);
00261 H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
00262 H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
00263                        haddr_t addr, hsize_t size);
00264 H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type);
00265 H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa);
00266 H5_DLL haddr_t H5FDget_eof(H5FD_t *file);
00267 H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void**file_handle);
00268 H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
00269                        haddr_t addr, size_t size, void *buf/*out*/);
00270 H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
00271                         haddr_t addr, size_t size, const void *buf);
00272 H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, unsigned closing);
00273 H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
00274 
00275 #ifdef __cplusplus
00276 }
00277 #endif
00278 #endif
00279