HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
H5FDpublic.h
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2  * Copyright by The HDF Group. *
3  * Copyright by the Board of Trustees of the University of Illinois. *
4  * All rights reserved. *
5  * *
6  * This file is part of HDF5. The full HDF5 copyright notice, including *
7  * terms governing use, modification, and redistribution, is contained in *
8  * the files COPYING and Copyright.html. COPYING can be found at the root *
9  * of the source code distribution tree; Copyright.html can be found at the *
10  * root level of an installed copy of the electronic HDF5 document set and *
11  * is linked from the top-level documents page. It can also be found at *
12  * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
13  * access to either file, you may request a copy from help@hdfgroup.org. *
14  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /*
17  * Programmer: Robb Matzke <matzke@llnl.gov>
18  * Monday, July 26, 1999
19  */
20 #ifndef _H5FDpublic_H
21 #define _H5FDpublic_H
22 
23 #include "H5public.h"
24 #include "H5Fpublic.h" /*for H5F_close_degree_t */
25 
26 #define H5_HAVE_VFL 1 /*define a convenient app feature test*/
27 #define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */
28 
29 /* Types of allocation requests: see H5Fpublic.h */
30 typedef enum H5F_mem_t H5FD_mem_t;
31 
32 /* Map "fractal heap" header blocks to 'ohdr' type file memory, since its
33  * a fair amount of work to add a new kind of file memory and they are similar
34  * enough to object headers and probably too minor to deserve their own type.
35  *
36  * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they
37  * are similar to fractal heap header blocks.
38  *
39  * Map "fractal heap" direct blocks to 'lheap' type file memory, since they
40  * will be replacing local heaps.
41  *
42  * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they
43  * represent large objects that are directly stored in the file.
44  *
45  * -QAK
46  */
47 #define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR
48 #define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR
49 #define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP
50 #define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW
51 
52 /* Map "free space" header blocks to 'ohdr' type file memory, since its
53  * a fair amount of work to add a new kind of file memory and they are similar
54  * enough to object headers and probably too minor to deserve their own type.
55  *
56  * Map "free space" serialized sections to 'lheap' type file memory, since they
57  * are similar enough to local heap info.
58  *
59  * -QAK
60  */
61 #define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR
62 #define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP
63 
64 /* Map "shared object header message" master table to 'ohdr' type file memory,
65  * since its a fair amount of work to add a new kind of file memory and they are
66  * similar enough to object headers and probably too minor to deserve their own
67  * type.
68  *
69  * Map "shared object header message" indices to 'btree' type file memory,
70  * since they are similar enough to B-tree nodes.
71  *
72  * -QAK
73  */
74 #define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR
75 #define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE
76 
77 /*
78  * A free-list map which maps all types of allocation requests to a single
79  * free list. This is useful for drivers that don't really care about
80  * keeping different requests segregated in the underlying file and which
81  * want to make most efficient reuse of freed memory. The use of the
82  * H5FD_MEM_SUPER free list is arbitrary.
83  */
84 #define H5FD_FLMAP_SINGLE { \
85  H5FD_MEM_SUPER, /*default*/ \
86  H5FD_MEM_SUPER, /*super*/ \
87  H5FD_MEM_SUPER, /*btree*/ \
88  H5FD_MEM_SUPER, /*draw*/ \
89  H5FD_MEM_SUPER, /*gheap*/ \
90  H5FD_MEM_SUPER, /*lheap*/ \
91  H5FD_MEM_SUPER /*ohdr*/ \
92 }
93 
94 /*
95  * A free-list map which segregates requests into `raw' or `meta' data
96  * pools.
97  */
98 #define H5FD_FLMAP_DICHOTOMY { \
99  H5FD_MEM_SUPER, /*default*/ \
100  H5FD_MEM_SUPER, /*super*/ \
101  H5FD_MEM_SUPER, /*btree*/ \
102  H5FD_MEM_DRAW, /*draw*/ \
103  H5FD_MEM_DRAW, /*gheap*/ \
104  H5FD_MEM_SUPER, /*lheap*/ \
105  H5FD_MEM_SUPER /*ohdr*/ \
106 }
107 
108 /*
109  * The default free list map which causes each request type to use it's own
110  * free-list.
111  */
112 #define H5FD_FLMAP_DEFAULT { \
113  H5FD_MEM_DEFAULT, /*default*/ \
114  H5FD_MEM_DEFAULT, /*super*/ \
115  H5FD_MEM_DEFAULT, /*btree*/ \
116  H5FD_MEM_DEFAULT, /*draw*/ \
117  H5FD_MEM_DEFAULT, /*gheap*/ \
118  H5FD_MEM_DEFAULT, /*lheap*/ \
119  H5FD_MEM_DEFAULT /*ohdr*/ \
120 }
121 
122 
123 /* Define VFL driver features that can be enabled on a per-driver basis */
124 /* These are returned with the 'query' function pointer in H5FD_class_t */
125  /*
126  * Defining the H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that
127  * the library will attempt to allocate a larger block for metadata and
128  * then sub-allocate each metadata request from that larger block.
129  */
130 #define H5FD_FEAT_AGGREGATE_METADATA 0x00000001
131  /*
132  * Defining the H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that
133  * the library will attempt to cache metadata as it is written to the file
134  * and build up a larger block of metadata to eventually pass to the VFL
135  * 'write' routine.
136  *
137  * Distinguish between updating the metadata accumulator on writes and
138  * reads. This is particularly (perhaps only, even) important for MPI-I/O
139  * where we guarantee that writes are collective, but reads may not be.
140  * If we were to allow the metadata accumulator to be written during a
141  * read operation, the application would hang.
142  */
143 #define H5FD_FEAT_ACCUMULATE_METADATA_WRITE 0x00000002
144 #define H5FD_FEAT_ACCUMULATE_METADATA_READ 0x00000004
145 #define H5FD_FEAT_ACCUMULATE_METADATA (H5FD_FEAT_ACCUMULATE_METADATA_WRITE|H5FD_FEAT_ACCUMULATE_METADATA_READ)
146  /*
147  * Defining the H5FD_FEAT_DATA_SIEVE for a VFL driver means that
148  * the library will attempt to cache raw data as it is read from/written to
149  * a file in a "data seive" buffer. See Rajeev Thakur's papers:
150  * http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz
151  * http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz
152  */
153 #define H5FD_FEAT_DATA_SIEVE 0x00000008
154  /*
155  * Defining the H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that
156  * the library will attempt to allocate a larger block for "small" raw data
157  * and then sub-allocate "small" raw data requests from that larger block.
158  */
159 #define H5FD_FEAT_AGGREGATE_SMALLDATA 0x00000010
160  /*
161  * Defining the H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that
162  * the library will ignore the driver info that is encoded in the file
163  * for the VFL driver. (This will cause the driver info to be eliminated
164  * from the file when it is flushed/closed, if the file is opened R/W).
165  */
166 #define H5FD_FEAT_IGNORE_DRVRINFO 0x00000020
167  /*
168  * Defining the H5FD_FEAT_DIRTY_SBLK_LOAD for a VFL driver means that
169  * the library will mark the superblock dirty when the file is opened
170  * R/W. This will cause the driver info to be re-encoded when the file
171  * is flushed/closed.
172  */
173 #define H5FD_FEAT_DIRTY_SBLK_LOAD 0x00000040
174  /*
175  * Defining the H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that
176  * the handle for the VFD (returned with the 'get_handle' callback) is
177  * of type 'int' and is compatible with POSIX I/O calls.
178  */
179 #define H5FD_FEAT_POSIX_COMPAT_HANDLE 0x00000080
180  /*
181  * Defining the H5FD_FEAT_ALLOW_FILE_IMAGE for a VFL driver means that
182  * the driver is able to use a file image in the fapl as the initial
183  * contents of a file.
184  */
185 #define H5FD_FEAT_ALLOW_FILE_IMAGE 0x00000400
186  /*
187  * Defining the H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS for a VFL driver
188  * means that the driver is able to use callbacks to make a copy of the
189  * image to store in memory.
190  */
191 #define H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS 0x00000800
192 
193 
194 /* Forward declaration */
195 typedef struct H5FD_t H5FD_t;
196 
197 /* Class information for each file driver */
198 typedef struct H5FD_class_t {
199  const char *name;
202  hsize_t (*sb_size)(H5FD_t *file);
203  herr_t (*sb_encode)(H5FD_t *file, char *name/*out*/,
204  unsigned char *p/*out*/);
205  herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p);
206  size_t fapl_size;
207  void * (*fapl_get)(H5FD_t *file);
208  void * (*fapl_copy)(const void *fapl);
209  herr_t (*fapl_free)(void *fapl);
210  size_t dxpl_size;
211  void * (*dxpl_copy)(const void *dxpl);
212  herr_t (*dxpl_free)(void *dxpl);
213  H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl,
214  haddr_t maxaddr);
215  herr_t (*close)(H5FD_t *file);
216  int (*cmp)(const H5FD_t *f1, const H5FD_t *f2);
217  herr_t (*query)(const H5FD_t *f1, unsigned long *flags);
218  herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map);
220  herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
221  haddr_t addr, hsize_t size);
224  haddr_t (*get_eof)(const H5FD_t *file);
225  herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void**file_handle);
227  haddr_t addr, size_t size, void *buffer);
229  haddr_t addr, size_t size, const void *buffer);
230  herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, unsigned closing);
231  herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
232  herr_t (*lock)(H5FD_t *file, unsigned char *oid, unsigned lock_type, hbool_t last);
233  herr_t (*unlock)(H5FD_t *file, unsigned char *oid, hbool_t last);
235 } H5FD_class_t;
236 
237 /* A free list is a singly-linked list of address/size pairs. */
238 typedef struct H5FD_free_t {
241  struct H5FD_free_t *next;
242 } H5FD_free_t;
243 
244 /*
245  * The main datatype for each driver. Public fields common to all drivers
246  * are declared here and the driver appends private fields in memory.
247  */
248 struct H5FD_t {
249  hid_t driver_id; /*driver ID for this file */
250  const H5FD_class_t *cls; /*constant class info */
251  unsigned long fileno; /* File 'serial' number */
252  unsigned long feature_flags; /* VFL Driver feature Flags */
253  haddr_t maxaddr; /* For this file, overrides class */
254  haddr_t base_addr; /* Base address for HDF5 data w/in file */
255 
256  /* Space allocation management fields */
257  hsize_t threshold; /* Threshold for alignment */
258  hsize_t alignment; /* Allocation alignment */
259 };
260 
261 /* Define enum for the source of file image callbacks */
262 typedef enum {
272 
273 /* Define structure to hold file image callbacks */
274 typedef struct {
275  void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op,
276  void *udata);
277  void *(*image_memcpy)(void *dest, const void *src, size_t size,
278  H5FD_file_image_op_t file_image_op, void *udata);
279  void *(*image_realloc)(void *ptr, size_t size,
280  H5FD_file_image_op_t file_image_op, void *udata);
281  herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op,
282  void *udata);
283  void *(*udata_copy)(void *udata);
284  herr_t (*udata_free)(void *udata);
285  void *udata;
287 
288 #ifdef __cplusplus
289 extern "C" {
290 #endif
291 
292 /* Function prototypes */
294 H5_DLL herr_t H5FDunregister(hid_t driver_id);
295 H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id,
296  haddr_t maxaddr);
298 H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2);
299 H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags);
301 H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
302  haddr_t addr, hsize_t size);
306 H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void**file_handle);
307 H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
308  haddr_t addr, size_t size, void *buf/*out*/);
309 H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
310  haddr_t addr, size_t size, const void *buf);
311 H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, unsigned closing);
312 H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
313 
314 #ifdef __cplusplus
315 }
316 #endif
317 #endif
318 
herr_t(* fapl_free)(void *fapl)
Definition: H5FDpublic.h:209
int(* cmp)(const H5FD_t *f1, const H5FD_t *f2)
Definition: H5FDpublic.h:216
H5_DLL H5FD_t * H5FDopen(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr)
herr_t(* sb_decode)(H5FD_t *f, const char *name, const unsigned char *p)
Definition: H5FDpublic.h:205
unsigned int hbool_t
Definition: H5public.h:125
herr_t(* free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size)
Definition: H5FDpublic.h:220
H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type)
H5_DLL herr_t H5FDunregister(hid_t driver_id)
png_voidp ptr
Definition: png.h:2145
hsize_t alignment
Definition: H5FDpublic.h:258
H5FD_file_image_op_t
Definition: H5FDpublic.h:262
haddr_t maxaddr
Definition: H5FDpublic.h:200
#define H5_DLL
Definition: H5api_adpt.h:406
herr_t(* truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing)
Definition: H5FDpublic.h:231
int herr_t
Definition: H5public.h:107
GLbitfield flags
Definition: glcorearb.h:1595
herr_t(* write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, const void *buffer)
Definition: H5FDpublic.h:228
haddr_t(* alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size)
Definition: H5FDpublic.h:219
unsigned long long hsize_t
Definition: H5public.h:151
struct H5FD_free_t * next
Definition: H5FDpublic.h:241
haddr_t base_addr
Definition: H5FDpublic.h:254
GLuint buffer
Definition: glcorearb.h:659
herr_t(* sb_encode)(H5FD_t *file, char *name, unsigned char *p)
Definition: H5FDpublic.h:203
GLsizeiptr size
Definition: glcorearb.h:663
herr_t(* lock)(H5FD_t *file, unsigned char *oid, unsigned lock_type, hbool_t last)
Definition: H5FDpublic.h:232
H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags)
hid_t driver_id
Definition: H5FDpublic.h:249
GLfloat f
Definition: glcorearb.h:1925
struct H5FD_class_t H5FD_class_t
H5FD_mem_t fl_map[H5FD_MEM_NTYPES]
Definition: H5FDpublic.h:234
H5_DLL herr_t H5FDclose(H5FD_t *file)
uint64_t haddr_t
Definition: H5public.h:163
H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2)
haddr_t(* get_eoa)(const H5FD_t *file, H5FD_mem_t type)
Definition: H5FDpublic.h:222
herr_t(* set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr)
Definition: H5FDpublic.h:223
hsize_t size
Definition: H5FDpublic.h:240
haddr_t addr
Definition: H5FDpublic.h:239
struct H5FD_free_t H5FD_free_t
herr_t(* dxpl_free)(void *dxpl)
Definition: H5FDpublic.h:212
int hid_t
Definition: H5Ipublic.h:56
GLuint const GLchar * name
Definition: glcorearb.h:785
const H5FD_class_t * cls
Definition: H5FDpublic.h:250
enum H5F_mem_t H5FD_mem_t
Definition: H5FDpublic.h:30
herr_t(* get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map)
Definition: H5FDpublic.h:218
herr_t(* close)(H5FD_t *file)
Definition: H5FDpublic.h:215
H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing)
GLenum GLuint GLenum GLsizei const GLchar * buf
Definition: glcorearb.h:2539
haddr_t maxaddr
Definition: H5FDpublic.h:253
H5F_mem_t
Definition: H5Fpublic.h:120
const char * name
Definition: H5FDpublic.h:199
H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, const void *buf)
H5_DLL hid_t H5FDregister(const H5FD_class_t *cls)
typedef int
Definition: png.h:1175
unsigned long fileno
Definition: H5FDpublic.h:251
hsize_t threshold
Definition: H5FDpublic.h:257
unsigned long feature_flags
Definition: H5FDpublic.h:252
hsize_t(* sb_size)(H5FD_t *file)
Definition: H5FDpublic.h:202
size_t dxpl_size
Definition: H5FDpublic.h:210
H5F_close_degree_t fc_degree
Definition: H5FDpublic.h:201
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
H5F_close_degree_t
Definition: H5Fpublic.h:95
herr_t(* read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, void *buffer)
Definition: H5FDpublic.h:226
size_t fapl_size
Definition: H5FDpublic.h:206
H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, void *buf)
H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa)
herr_t(* query)(const H5FD_t *f1, unsigned long *flags)
Definition: H5FDpublic.h:217
H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size)
H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void **file_handle)
herr_t(* get_handle)(H5FD_t *file, hid_t fapl, void **file_handle)
Definition: H5FDpublic.h:225
H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, unsigned closing)
H5_DLL haddr_t H5FDget_eof(H5FD_t *file)
herr_t(* unlock)(H5FD_t *file, unsigned char *oid, hbool_t last)
Definition: H5FDpublic.h:233
herr_t(* flush)(H5FD_t *file, hid_t dxpl_id, unsigned closing)
Definition: H5FDpublic.h:230
haddr_t(* get_eof)(const H5FD_t *file)
Definition: H5FDpublic.h:224
GLenum src
Definition: glcorearb.h:1792
H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size)