summaryrefslogtreecommitdiffstats
path: root/src/H5Fpublic.h
blob: 139ab89d7902b5973b1c46fa63cecaf15c0ba705 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * This file contains public declarations for the H5F module.
 */
#ifndef _H5Fpublic_H
#define _H5Fpublic_H

/* Public header files needed by this file */
#include "H5public.h"
#include "H5ACpublic.h"
#include "H5Ipublic.h"

/* When this header is included from a private header, don't make calls to H5check() */
#undef H5CHECK
#ifndef _H5private_H
#define H5CHECK H5check(),
#else /* _H5private_H */
#define H5CHECK
#endif /* _H5private_H */

/* When this header is included from a private HDF5 header, don't make calls to H5open() */
#undef H5OPEN
#ifndef _H5private_H
#define H5OPEN H5open(),
#else /* _H5private_H */
#define H5OPEN
#endif /* _H5private_H */

/*
 * These are the bits that can be passed to the `flags' argument of
 * H5Fcreate() and H5Fopen(). Use the bit-wise OR operator (|) to combine
 * them as needed.  As a side effect, they call H5check_version() to make sure
 * that the application is compiled with a version of the hdf5 header files
 * which are compatible with the library to which the application is linked.
 * We're assuming that these constants are used rather early in the hdf5
 * session.
 */
#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /*absence of rdwr => rd-only */
#define H5F_ACC_RDWR   (H5CHECK H5OPEN 0x0001u) /*open for read and write    */
#define H5F_ACC_TRUNC  (H5CHECK H5OPEN 0x0002u) /*overwrite existing files   */
#define H5F_ACC_EXCL   (H5CHECK H5OPEN 0x0004u) /*fail if file already exists*/
/* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */
#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /*create non-existing files  */
#define H5F_ACC_SWMR_WRITE                                                                                   \
    (H5CHECK 0x0020u) /*indicate that this file is                                                           \
                       * open for writing in a                                                               \
                       * single-writer/multi-reader (SWMR)                                                   \
                       * scenario.  Note that the                                                            \
                       * process(es) opening the file                                                        \
                       * for reading must open the file                                                      \
                       * with RDONLY access, and use                                                         \
                       * the special "SWMR_READ" access                                                      \
                       * flag. */
#define H5F_ACC_SWMR_READ                                                                                    \
    (H5CHECK 0x0040u) /*indicate that this file is                                                           \
                       * open for reading in a                                                               \
                       * single-writer/multi-reader (SWMR)                                                   \
                       * scenario.  Note that the                                                            \
                       * process(es) opening the file                                                        \
                       * for SWMR reading must also                                                          \
                       * open the file with the RDONLY                                                       \
                       * flag.  */

/* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the
 * parent file. */
#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /*ignore setting on lapl     */

/* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */
#define H5F_OBJ_FILE     (0x0001u) /* File objects */
#define H5F_OBJ_DATASET  (0x0002u) /* Dataset objects */
#define H5F_OBJ_GROUP    (0x0004u) /* Group objects */
#define H5F_OBJ_DATATYPE (0x0008u) /* Named datatype objects */
#define H5F_OBJ_ATTR     (0x0010u) /* Attribute objects */
#define H5F_OBJ_ALL      (H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR)
#define H5F_OBJ_LOCAL    (0x0020u) /* Restrict search to objects opened through current file ID */
/* (as opposed to objects opened through any file ID accessing this file) */

#define H5F_FAMILY_DEFAULT (hsize_t)0

#ifdef H5_HAVE_PARALLEL
/*
 * Use this constant string as the MPI_Info key to set H5Fmpio debug flags.
 * To turn on H5Fmpio debug flags, set the MPI_Info value with this key to
 * have the value of a string consisting of the characters that turn on the
 * desired flags.
 */
#define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key"
#endif /* H5_HAVE_PARALLEL */

/* The difference between a single file and a set of mounted files */
typedef enum H5F_scope_t {
    H5F_SCOPE_LOCAL  = 0, /*specified file handle only        */
    H5F_SCOPE_GLOBAL = 1  /*entire virtual file            */
} H5F_scope_t;

/* Unlimited file size for H5Pset_external() */
#define H5F_UNLIMITED ((hsize_t)(-1L))

/* How does file close behave?
 * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL
 * H5F_CLOSE_WEAK    - file closes only after all opened objects are closed
 * H5F_CLOSE_SEMI    - if no opened objects, file is close; otherwise, file
            close fails
 * H5F_CLOSE_STRONG  - if there are opened objects, close them first, then
            close file
 */
typedef enum H5F_close_degree_t {
    H5F_CLOSE_DEFAULT = 0,
    H5F_CLOSE_WEAK    = 1,
    H5F_CLOSE_SEMI    = 2,
    H5F_CLOSE_STRONG  = 3
} H5F_close_degree_t;

/* Current "global" information about file */
typedef struct H5F_info2_t {
    struct {
        unsigned version;        /* Superblock version # */
        hsize_t  super_size;     /* Superblock size */
        hsize_t  super_ext_size; /* Superblock extension size */
    } super;
    struct {
        unsigned version;   /* Version # of file free space management */
        hsize_t  meta_size; /* Free space manager metadata size */
        hsize_t  tot_space; /* Amount of free space in the file */
    } free;
    struct {
        unsigned     version;   /* Version # of shared object header info */
        hsize_t      hdr_size;  /* Shared object header message header size */
        H5_ih_info_t msgs_info; /* Shared object header message index & heap size */
    } sohm;
} H5F_info2_t;

/*
 * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT
 * should not change other than adding new types to the end. These numbers
 * might appear in files.
 *
 * Note: please change the log VFD flavors array if you change this
 * enumeration.
 */
typedef enum H5F_mem_t {
    H5FD_MEM_NOLIST = -1, /* Data should not appear in the free list.
                           * Must be negative.
                           */
    H5FD_MEM_DEFAULT = 0, /* Value not yet set.  Can also be the
                           * datatype set in a larger allocation
                           * that will be suballocated by the library.
                           * Must be zero.
                           */
    H5FD_MEM_SUPER = 1,   /* Superblock data */
    H5FD_MEM_BTREE = 2,   /* B-tree data */
    H5FD_MEM_DRAW  = 3,   /* Raw data (content of datasets, etc.) */
    H5FD_MEM_GHEAP = 4,   /* Global heap data */
    H5FD_MEM_LHEAP = 5,   /* Local heap data */
    H5FD_MEM_OHDR  = 6,   /* Object header data */

    H5FD_MEM_NTYPES /* Sentinel value - must be last */
} H5F_mem_t;

/* Free space section information */
typedef struct H5F_sect_info_t {
    haddr_t addr; /* Address of free space section */
    hsize_t size; /* Size of free space section */
} H5F_sect_info_t;

/* Library's format versions */
typedef enum H5F_libver_t {
    H5F_LIBVER_ERROR    = -1,
    H5F_LIBVER_EARLIEST = 0, /* Use the earliest possible format for storing objects */
    H5F_LIBVER_V18      = 1, /* Use the latest v18 format for storing objects */
    H5F_LIBVER_V110     = 2, /* Use the latest v110 format for storing objects */
    H5F_LIBVER_V112     = 3, /* Use the latest v112 format for storing objects */
    H5F_LIBVER_V114     = 4, /* Use the latest v114 format for storing objects */
    H5F_LIBVER_NBOUNDS
} H5F_libver_t;

#define H5F_LIBVER_LATEST H5F_LIBVER_V114

/* File space handling strategy */
typedef enum H5F_fspace_strategy_t {
    H5F_FSPACE_STRATEGY_FSM_AGGR =
        0, /* Mechanisms: free-space managers, aggregators, and virtual file drivers */
           /* This is the library default when not set */
    H5F_FSPACE_STRATEGY_PAGE =
        1, /* Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */
    H5F_FSPACE_STRATEGY_AGGR = 2, /* Mechanisms: aggregators and virtual file drivers */
    H5F_FSPACE_STRATEGY_NONE = 3, /* Mechanisms: virtual file drivers */
    H5F_FSPACE_STRATEGY_NTYPES    /* must be last */
} H5F_fspace_strategy_t;

/* Deprecated: File space handling strategy for release 1.10.0 */
/* They are mapped to H5F_fspace_strategy_t as defined above from release 1.10.1 onwards */
typedef enum H5F_file_space_type_t {
    H5F_FILE_SPACE_DEFAULT     = 0, /* Default (or current) free space strategy setting */
    H5F_FILE_SPACE_ALL_PERSIST = 1, /* Persistent free space managers, aggregators, virtual file driver */
    H5F_FILE_SPACE_ALL         = 2, /* Non-persistent free space managers, aggregators, virtual file driver */
                                    /* This is the library default */
    H5F_FILE_SPACE_AGGR_VFD = 3,    /* Aggregators, Virtual file driver */
    H5F_FILE_SPACE_VFD      = 4,    /* Virtual file driver */
    H5F_FILE_SPACE_NTYPES           /* must be last */
} H5F_file_space_type_t;

/* Data structure to report the collection of read retries for metadata items with checksum */
/* Used by public routine H5Fget_metadata_read_retry_info() */
#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
typedef struct H5F_retry_info_t {
    unsigned  nbins;
    uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
} H5F_retry_info_t;

/* Callback for H5Pset_object_flush_cb() in a file access property list */
typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata);

/* VFD SWMR configuration data used by H5Pset/get_vfd_swmr_config */
#define H5F__CURR_VFD_SWMR_CONFIG_VERSION 1
#define H5F__MAX_VFD_SWMR_FILE_NAME_LEN   1024
#define H5F__MAX_PB_EXPANSION_THRESHOLD   100
/*
 *  struct H5F_vfd_swmr_config_t
 *
 *  Instances of H5F_vfd_swmr_config_t are used by VFD SWMR writers and readers
 *  to pass necessary configuration data to the HDF5 library on file open (or
 *  creation, in the case of writers).
 *
 *  The fields of the structure are discussed below:
 *      version:
 *          An integer field indicating the version of the H5F_vfd_swmr_config
 *          structure used.  This field must always be set to a known version
 *          number.  The most recent version of the structure will always be
 *          H5F__CURR_VFD_SWMR_CONFIG_VERSION.
 *
 *      tick_len:
 *          An integer field containing the length of a tick in tenths of
 *          a second.  If tick_len is zero, end of tick processing may only be
 *          triggered manually via the H5Fvfd_swmr_end_tick() function.
 *
 *      max_lag:
 *          An integer field indicating the maximum expected lag (in ticks)
 *          between the writer and the readers.  This value must be at least 3,
 *          with 10 being the recommended minimum value.
 *
 *      writer:
 *          A boolean flag indicating whether the file opened with this FAPL entry
 *          will be opened R/W. (i.e. as a VFD SWMR writer)
 *
 *      flush_raw_data:
 *          A boolean flag indicating whether raw data should be flushed
 *          as part of the end of tick processing.  If set to TRUE, raw
 *          data will be flushed and thus be consistent with the metadata file.
 *          However, this will also greatly increase end of tick I/O, and will
 *          likely break any real time guarantees unless a very large tick_len
 *          is selected.
 *
 *      md_pages_reserved:
 *          The `md_pages_reserved` parameter tells how many pages to reserve
 *          at the beginning of the shadow file for the shadow-file header
 *          and the shadow index.  The header has an entire page to itself.
 *          The remaining `md_pages_reserved - 1` pages are reserved for the
 *          shadow index.  If the index grows larger than its initial
 *          allocation, then it will move to a new location in the shadow file,
 *          and the initial allocation will be reclaimed.  `md_pages_reserved`
 *          must be at least 2.
 *
 *      pb_expansion_threshold:
 *          An integer field indicating the threshold for the page buffer size.
 *          During a tick, the page buffer must expand as necessary to retain copies
 *          of all modified metadata pages and multi-page metadata entries.
 *          If the page buffer size exceeds this thresold, an early end of tick
 *          will be triggered.
 *          Note that this is not a limit on the maximum page buffer size, as the
 *          metadata cache is flushed as part of end of tick processing.
 *          This threshold must be in the range [0, 100].  If the threshold is 0,
 *          the feature is disabled.  For all other values, the page buffer size is
 *          multiplied by this threshold.  If this value is exceeded, an early end
 *          of tick is triggered.
 *
 *      md_file_path:
 *          POSIX: this field contains the path of the metadata file.
 *          NFS: it contains the path and base name of the metadata file
 *          updater files.
 *          Object store: it contains the base URL for the objects used
 *          to store metadata file updater objects.
 *
 *      log_file_path:
 *          This field contains the path to the log file.  If defined, this path should
 *          be unique to each process.  If this field contains the empty string, a log
 *          file will not be created.
 *
 */
typedef struct H5F_vfd_swmr_config_t {
    int32_t  version;
    uint32_t tick_len;
    uint32_t max_lag;
    hbool_t  writer;
    hbool_t  flush_raw_data;
    uint32_t md_pages_reserved;
    uint32_t pb_expansion_threshold;
    char     md_file_path[H5F__MAX_VFD_SWMR_FILE_NAME_LEN + 1];
    char     log_file_path[H5F__MAX_VFD_SWMR_FILE_NAME_LEN + 1];
} H5F_vfd_swmr_config_t;

/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif

H5_DLL htri_t   H5Fis_accessible(const char *container_name, hid_t fapl_id);
H5_DLL hid_t    H5Fcreate(const char *filename, unsigned flags, hid_t create_plist, hid_t access_plist);
H5_DLL hid_t    H5Fopen(const char *filename, unsigned flags, hid_t access_plist);
H5_DLL hid_t    H5Freopen(hid_t file_id);
H5_DLL herr_t   H5Fflush(hid_t object_id, H5F_scope_t scope);
H5_DLL herr_t   H5Fclose(hid_t file_id);
H5_DLL herr_t   H5Fdelete(const char *filename, hid_t fapl_id);
H5_DLL hid_t    H5Fget_create_plist(hid_t file_id);
H5_DLL hid_t    H5Fget_access_plist(hid_t file_id);
H5_DLL herr_t   H5Fget_intent(hid_t file_id, unsigned *intent);
H5_DLL herr_t   H5Fget_fileno(hid_t file_id, unsigned long *fileno);
H5_DLL ssize_t  H5Fget_obj_count(hid_t file_id, unsigned types);
H5_DLL ssize_t  H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list);
H5_DLL herr_t   H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle);
H5_DLL herr_t   H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist);
H5_DLL herr_t   H5Funmount(hid_t loc, const char *name);
H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
H5_DLL herr_t   H5Fget_filesize(hid_t file_id, hsize_t *size);
H5_DLL herr_t   H5Fget_eoa(hid_t file_id, haddr_t *eoa);
H5_DLL herr_t   H5Fincrement_filesize(hid_t file_id, hsize_t increment);
H5_DLL ssize_t  H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
H5_DLL herr_t   H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
H5_DLL herr_t   H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
H5_DLL herr_t   H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr);
H5_DLL herr_t   H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr,
                                size_t *cur_size_ptr, int *cur_num_entries_ptr);
H5_DLL herr_t   H5Freset_mdc_hit_rate_stats(hid_t file_id);
H5_DLL ssize_t  H5Fget_name(hid_t obj_id, char *name, size_t size);
H5_DLL herr_t   H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo);
H5_DLL herr_t   H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info);
H5_DLL herr_t   H5Fstart_swmr_write(hid_t file_id);
H5_DLL ssize_t  H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects,
                                     H5F_sect_info_t *sect_info /*out*/);
H5_DLL herr_t   H5Fclear_elink_file_cache(hid_t file_id);
H5_DLL herr_t   H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t high);
H5_DLL herr_t   H5Fstart_mdc_logging(hid_t file_id);
H5_DLL herr_t   H5Fstop_mdc_logging(hid_t file_id);
H5_DLL herr_t   H5Fget_mdc_logging_status(hid_t            file_id,
                                          /*OUT*/ hbool_t *is_enabled,
                                          /*OUT*/ hbool_t *is_currently_logging);
H5_DLL herr_t   H5Fformat_convert(hid_t fid);
H5_DLL herr_t   H5Freset_page_buffering_stats(hid_t file_id);
H5_DLL herr_t   H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], unsigned hits[2],
                                            unsigned misses[2], unsigned evictions[2], unsigned bypasses[2]);
H5_DLL herr_t   H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size);
H5_DLL herr_t   H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize);
H5_DLL herr_t   H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize);

/* VFD SWMR */
H5_DLL herr_t H5Fvfd_swmr_end_tick(hid_t file_id);
H5_DLL herr_t H5Fvfd_swmr_disable_end_of_tick(hid_t file_id);
H5_DLL herr_t H5Fvfd_swmr_enable_end_of_tick(hid_t file_id);
H5_DLL bool   vfd_swmr_writer_may_increase_tick_to(uint64_t, bool);
H5_DLL void   vfd_swmr_reader_did_increase_tick_to(uint64_t);

#ifdef H5_HAVE_PARALLEL
H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#endif /* H5_HAVE_PARALLEL */

/* Symbols defined for compatibility with previous versions of the HDF5 API.
 *
 * Use of these symbols is deprecated.
 */
#ifndef H5_NO_DEPRECATED_SYMBOLS

/* Macros */
#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /*print debug info (deprecated)*/

/* Typedefs */

/* Current "global" information about file */
typedef struct H5F_info1_t {
    hsize_t super_ext_size; /* Superblock extension size */
    struct {
        hsize_t      hdr_size;  /* Shared object header message header size */
        H5_ih_info_t msgs_info; /* Shared object header message index & heap size */
    } sohm;
} H5F_info1_t;

/* Function prototypes */
H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo);
H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format);
H5_DLL htri_t H5Fis_hdf5(const char *filename);

#endif /* H5_NO_DEPRECATED_SYMBOLS */

#ifdef __cplusplus
}
#endif
#endif /* _H5Fpublic_H */