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 COPYING file, which can be found at the root of the source code       *
9  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
10  * If you do not have access to either file, you may request a copy from     *
11  * help@hdfgroup.org.                                                        *
12  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
13 
14 /*-------------------------------------------------------------------------
15  *
16  * Created:     H5EAprivate.h
17  *              Jun 17 2008
18  *              Quincey Koziol
19  *
20  * Purpose:     Private header for library accessible extensible
21  *              array routines.
22  *
23  *-------------------------------------------------------------------------
24  */
25 
26 #ifndef H5EAprivate_H
27 #define H5EAprivate_H
28 
29 /* Include package's public header */
30 #ifdef NOT_YET
31 #include "H5EApublic.h"
32 #endif /* NOT_YET */
33 
34 /* Private headers needed by this file */
35 #include "H5ACprivate.h" /* Metadata cache               */
36 #include "H5Fprivate.h"  /* File access                  */
37 
38 /**************************/
39 /* Library Private Macros */
40 /**************************/
41 
42 /****************************/
43 /* Library Private Typedefs */
44 /****************************/
45 
46 /* Extensible array class IDs */
47 typedef enum H5EA_cls_id_t {
48     H5EA_CLS_CHUNK_ID = 0,  /* Extensible array is for indexing dataset chunks w/o filters */
49     H5EA_CLS_FILT_CHUNK_ID, /* Extensible array is for indexing dataset chunks w/filters */
50 
51     /* Start real class IDs at 0 -QAK */
52     /* (keep these last) */
53     H5EA_CLS_TEST_ID, /* Extensible array is for testing (do not use for actual data) */
54     H5EA_NUM_CLS_ID   /* Number of Extensible Array class IDs (must be last) */
55 } H5EA_cls_id_t;
56 
57 /*
58  * Each type of element that can be stored in an extesible array has a
59  * variable of this type that contains class variables and methods.
60  */
61 typedef struct H5EA_class_t {
62     H5EA_cls_id_t id;            /* ID of Extensible Array class, as found in file */
63     const char *  name;          /* Name of class (for debugging) */
64     size_t        nat_elmt_size; /* Size of native (memory) element */
65 
66     /* Extensible array client callback methods */
67     void *(*crt_context)(void *udata); /* Create context for other callbacks */
68     herr_t (*dst_context)(void *ctx);  /* Destroy context */
69     herr_t (*fill)(void * nat_blk,
70                    size_t nelmts); /* Fill array of elements with encoded form of "missing element" value */
71     herr_t (*encode)(void *raw, const void *elmt, size_t nelmts,
72                      void *ctx); /* Encode elements from native form to disk storage form */
73     herr_t (*decode)(const void *raw, void *elmt, size_t nelmts,
74                      void *ctx); /* Decode elements from disk storage form to native form */
75     herr_t (*debug)(FILE *stream, int indent, int fwidth, hsize_t idx,
76                     const void *elmt);                /* Print an element for debugging */
77     void *(*crt_dbg_ctx)(H5F_t *f, haddr_t obj_addr); /* Create debugging context */
78     herr_t (*dst_dbg_ctx)(void *dbg_ctx);             /* Destroy debugging context */
79 } H5EA_class_t;
80 
81 /* Extensible array creation parameters */
82 typedef struct H5EA_create_t {
83     const H5EA_class_t *cls;           /* Class of extensible array to create */
84     uint8_t             raw_elmt_size; /* Element size in file (in bytes) */
85     uint8_t max_nelmts_bits; /* Log2(Max. # of elements in array) - i.e. # of bits needed to store max. # of
86                                 elements */
87     uint8_t idx_blk_elmts;   /* # of elements to store in index block */
88     uint8_t data_blk_min_elmts;        /* Min. # of elements per data block */
89     uint8_t sup_blk_min_data_ptrs;     /* Min. # of data block pointers for a super block */
90     uint8_t max_dblk_page_nelmts_bits; /* Log2(Max. # of elements in data block page) - i.e. # of bits needed
91                                           to store max. # of elements in data block page */
92 } H5EA_create_t;
93 
94 /* Extensible array metadata statistics info */
95 /* (If these are ever exposed to applications, don't let the application see
96  *      which fields are computed vs. which fields are stored. -QAK)
97  */
98 typedef struct H5EA_stat_t {
99     /* Non-stored (i.e. computed) fields */
100     struct {
101         hsize_t hdr_size;       /* Size of header */
102         hsize_t nindex_blks;    /* # of index blocks (should be 0 or 1) */
103         hsize_t index_blk_size; /* Size of index blocks allocated */
104     } computed;
105 
106     /* Stored fields */
107     struct {
108         hsize_t nsuper_blks;    /* # of super blocks */
109         hsize_t super_blk_size; /* Size of super blocks allocated */
110         hsize_t ndata_blks;     /* # of data blocks */
111         hsize_t data_blk_size;  /* Size of data blocks allocated */
112         hsize_t max_idx_set; /* Highest element index stored (+1 - i.e. if element 0 has been set, this value
113                                 with be '1', if no elements have been stored, this value will be '0') */
114         hsize_t nelmts;      /* # of elements "realized" */
115     } stored;
116 } H5EA_stat_t;
117 
118 /* Extensible array info (forward decl - defined in H5EApkg.h) */
119 typedef struct H5EA_t H5EA_t;
120 
121 /* Define the operator callback function pointer for H5EA_iterate() */
122 typedef int (*H5EA_operator_t)(hsize_t idx, const void *_elmt, void *_udata);
123 
124 /*****************************/
125 /* Library-private Variables */
126 /*****************************/
127 
128 /* The Extensible Array class for dataset chunks w/o filters*/
129 H5_DLLVAR const H5EA_class_t H5EA_CLS_CHUNK[1];
130 
131 /* The Extensible Array class for dataset chunks w/ filters*/
132 H5_DLLVAR const H5EA_class_t H5EA_CLS_FILT_CHUNK[1];
133 
134 /***************************************/
135 /* Library-private Function Prototypes */
136 /***************************************/
137 
138 /* General routines */
139 H5_DLL H5EA_t *H5EA_create(H5F_t *f, const H5EA_create_t *cparam, void *ctx_udata);
140 H5_DLL H5EA_t *H5EA_open(H5F_t *f, haddr_t ea_addr, void *ctx_udata);
141 H5_DLL herr_t  H5EA_get_nelmts(const H5EA_t *ea, hsize_t *nelmts);
142 H5_DLL herr_t  H5EA_get_addr(const H5EA_t *ea, haddr_t *addr);
143 H5_DLL herr_t  H5EA_set(const H5EA_t *ea, hsize_t idx, const void *elmt);
144 H5_DLL herr_t  H5EA_get(const H5EA_t *ea, hsize_t idx, void *elmt);
145 H5_DLL herr_t  H5EA_depend(H5EA_t *ea, H5AC_proxy_entry_t *parent);
146 H5_DLL herr_t  H5EA_iterate(H5EA_t *fa, H5EA_operator_t op, void *udata);
147 H5_DLL herr_t  H5EA_close(H5EA_t *ea);
148 H5_DLL herr_t  H5EA_delete(H5F_t *f, haddr_t ea_addr, void *ctx_udata);
149 H5_DLL herr_t  H5EA_patch_file(H5EA_t *fa, H5F_t *f);
150 
151 /* Statistics routines */
152 H5_DLL herr_t H5EA_get_stats(const H5EA_t *ea, H5EA_stat_t *stats);
153 
154 /* Debugging routines */
155 #ifdef H5EA_DEBUGGING
156 #endif /* H5EA_DEBUGGING */
157 
158 #endif /* H5EAprivate_H */
159