H5SMpkg.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:  James Laird <jlaird@ncsa.uiuc.edu>
00018  *              Thursday, March 30, 2006
00019  *
00020  * Purpose:     This file contains declarations which are visible only within
00021  *              the H5SM shared object header messages package.  Source files
00022  *              outside the H5SM package should include H5SMprivate.h instead.
00023  */
00024 #ifndef H5SM_PACKAGE
00025 #error "Do not include this file outside the H5SM package!"
00026 #endif
00027 
00028 #ifndef _H5SMpkg_H
00029 #define _H5SMpkg_H
00030 
00031 /* Get package's private header */
00032 #include "H5SMprivate.h"        /* Shared Object Header Messages        */
00033 
00034 /* Other private headers needed by this file */
00035 #include "H5B2private.h"        /* B-trees                              */
00036 #include "H5HFprivate.h"        /* Fractal heaps                        */
00037 
00038 
00039 /****************************/
00040 /* Package Macros           */
00041 /****************************/
00042 
00043 /* Size of checksum information (on disk) */
00044 #define H5SM_SIZEOF_CHECKSUM 4
00045 
00046 #define H5SM_HEAP_LOC_SIZE (                                                  \
00047         4                               /* Reference count */                 \
00048         + sizeof(H5O_fheap_id_t)        /* size of heap ID on disk */         \
00049     )
00050 
00051 #define H5SM_OH_LOC_SIZE(f) (                                                 \
00052         1                       /* reserved (possible flags?) */              \
00053         + 1                     /* message type ID */                         \
00054         + 2                     /* creation index of message in OH */         \
00055         + H5F_SIZEOF_ADDR(f)    /* address of OH */                           \
00056     )
00057 
00058 #define H5SM_SOHM_ENTRY_SIZE(f) (                                             \
00059         1                       /* Message location */                        \
00060         + 4                     /* Hash value */                              \
00061         + MAX(H5SM_HEAP_LOC_SIZE, H5SM_OH_LOC_SIZE(f))  /* Entry */           \
00062     )
00063 
00064 #define H5SM_TABLE_SIZE(f) (                                                  \
00065         H5_SIZEOF_MAGIC                 /* Signature */                       \
00066          + H5SM_SIZEOF_CHECKSUM         /* Checksum */                        \
00067     )
00068 
00069 #define H5SM_INDEX_HEADER_SIZE(f) (                                           \
00070         1                       /* Whether index is a list or B-tree */       \
00071         + 1                     /* Version of index format */                 \
00072         + 2                     /* Type of messages stored in the index */    \
00073         + 4                     /* Minimum size of messages to share */       \
00074         + (3 * 2)               /* B-tree cutoff, list cutoff, # of shared messages */ \
00075         + H5F_SIZEOF_ADDR(f)    /* Location of list or B-tree */              \
00076         + H5F_SIZEOF_ADDR(f)    /* Address of heap */                         \
00077     )
00078 
00079 #define H5SM_LIST_SIZE(f, num_mesg) (                                         \
00080          H5_SIZEOF_MAGIC                /* Signature */                       \
00081          + (H5SM_SOHM_ENTRY_SIZE(f) * num_mesg) /* Message entries */         \
00082          + H5SM_SIZEOF_CHECKSUM         /* Checksum */                        \
00083     )
00084 
00085 #define H5SM_B2_NODE_SIZE 512
00086 #define H5SM_B2_SPLIT_PERCENT 100
00087 #define H5SM_B2_MERGE_PERCENT 40
00088 
00089 #define H5SM_LIST_VERSION       0       /* Verion of Shared Object Header Message List Indexes */
00090 
00091 /****************************/
00092 /* Package Typedefs         */
00093 /****************************/
00094 
00095 /* There are a number of Shared Object Header Message-specific structs here.
00096  *
00097  * The H5SM_master_table_t is pointed to by the file superblock.  Since a file
00098  * can have more than one SOHM index, this table collects all the indexes into
00099  * one place.  It holds an array of H5SM_index_header_t structs.
00100  *
00101  * An H5SM_index_header_t is actually the for a given index.  It holds
00102  * the number of messages in the index, the types of messages in the index,
00103  * etc.  It also records whether the index is a list or a b-tree, and has
00104  * the address of the list or b-tree.
00105  *
00106  * If the index is a list, the address in the index header should be given
00107  * to the cache, which can load it into a H5SM_list_t struct.  This is mostly
00108  * just a header for the cache information; it contains a pointer back to
00109  * the index header and an unsorted array of messages.
00110  *
00111  * These messages are H5SM_sohm_t structs.  They hold the actual SOHM's
00112  * address, hash value, and refcount.
00113  *
00114  * If the index is a b-tree, the H5SM_index_header_t struct holds the address
00115  * of the b-tree instead of the address of a H5SM_list_t.  The B-tree's nodes
00116  * are still 'H5SM_sohm_t's.
00117  *
00118  * H5SM_mesg_key_t structs are used to search lists and B-trees for a certain
00119  * message.  They correspond to a message that hasn't yet been written to
00120  * disk.
00121  */
00122 
00123 /* Where a message is stored */
00124 typedef enum {
00125     H5SM_NO_LOC = -1,
00126     H5SM_IN_HEAP = 0,           /* Message is stored in the heap */
00127     H5SM_IN_OH                  /* Message is stored in an object header */
00128 } H5SM_storage_loc_t;
00129 
00130 /* Typedef for a record's location if it's stored in the heap */
00131 typedef struct {
00132     hsize_t ref_count;          /* Number of times this message is used in the file */
00133     H5O_fheap_id_t fheap_id;    /* ID of the OHM in the fractal heap */
00134 } H5SM_heap_loc_t;
00135 
00136 /* Typedef for a SOHM index node */
00137 typedef struct {
00138     H5SM_storage_loc_t location;        /* Type of message location */
00139     uint32_t hash;                      /* Hash value for encoded OHM */
00140     unsigned msg_type_id;               /* Message's type ID */
00141     union {
00142         H5O_mesg_loc_t mesg_loc;        /* Location of message in object header */
00143         H5SM_heap_loc_t heap_loc;       /* Heap ID for message in SOHM heap */
00144     } u;
00145 } H5SM_sohm_t;
00146 
00147 /* Types of message indices */
00148 typedef enum {
00149     H5SM_BADTYPE = -1,
00150     H5SM_LIST,                  /* Index is an unsorted list */
00151     H5SM_BTREE                  /* Index is a sorted B-tree */
00152 } H5SM_index_type_t;
00153 
00154 /* Typedef for a SOHM index header */
00155 typedef struct {
00156     unsigned mesg_types;        /* Bit flag vector of message types */
00157     size_t min_mesg_size;       /* number of messages being tracked */
00158     size_t list_max;            /* >= this many messages, index with a B-tree */
00159     size_t btree_min;           /* <= this many messages, index with a list again */
00160     size_t num_messages;        /* number of messages being tracked */
00161     H5SM_index_type_t index_type; /* Is the index a list or a B-tree? */
00162     haddr_t index_addr;         /* Address of the actual index (list or B-tree) */
00163     haddr_t heap_addr;          /* Address of the fheap used to store shared messages */
00164 } H5SM_index_header_t;
00165 
00166 /* Typedef for a SOHM list */
00167 typedef struct {
00168     /* Information for H5AC cache functions, _must_ be first field in structure */
00169     H5AC_info_t cache_info;
00170 
00171     H5SM_index_header_t *header;    /* Pointer to the corresponding index header */
00172     H5SM_sohm_t *messages;          /* Actual list, stored as an array */
00173 } H5SM_list_t;
00174 
00175 
00176 /* Typedef for shared object header message master table */
00177 struct H5SM_master_table_t {
00178     /* Information for H5AC cache functions, _must_ be first field in structure */
00179     H5AC_info_t cache_info;
00180 
00181     unsigned num_indexes;           /* Number of indexes */
00182     H5SM_index_header_t *indexes;   /* Array of num_indexes indexes */
00183 };
00184 
00185 /* Typedef for searching an index (list or B-tree) */
00186 typedef struct {
00187     H5F_t *file;                        /* File in which sharing is happening */
00188     hid_t dxpl_id;                      /* DXPL for sharing messages in heap */
00189     H5HF_t *fheap;                      /* The heap for this message type, open. */
00190     void *encoding;                     /* The message encoded, or NULL */
00191     size_t encoding_size;               /* Size of the encoding, or 0 */
00192     H5SM_sohm_t message;                /* The message to find/insert.
00193                                          * If the message doesn't yet have a
00194                                          * heap ID, the heap ID will be 0. */
00195 } H5SM_mesg_key_t;
00196 
00197 /*
00198  * Data exchange structure to pass through the fractal heap layer for the
00199  * H5HF_op function when computing a hash value for a message.
00200  */
00201 typedef struct {
00202     /* downward (internal) */
00203     unsigned    type_id;                /* Message type */
00204 
00205     /* upward */
00206     uint32_t    hash;                   /* Hash value */
00207 } H5SM_fh_ud_gh_t;
00208 
00209 /* Typedef to increment a reference count in the B-tree */
00210 typedef struct {
00211     H5SM_mesg_key_t *key;       /* IN: key for message being incremented */
00212     H5O_fheap_id_t fheap_id;    /* OUT: fheap ID of record */
00213     hid_t dxpl_id;
00214 } H5SM_incr_ref_opdata;
00215 
00216 
00217 /****************************/
00218 /* Package Variables        */
00219 /****************************/
00220 
00221 /* Declare free lists to manage H5SM structs */
00222 H5FL_EXTERN(H5SM_master_table_t);
00223 H5FL_ARR_EXTERN(H5SM_index_header_t);
00224 H5FL_EXTERN(H5SM_list_t);
00225 H5FL_ARR_EXTERN(H5SM_sohm_t);
00226 
00227 H5_DLLVAR const H5AC_class_t H5AC_SOHM_TABLE[1];
00228 H5_DLLVAR const H5AC_class_t H5AC_SOHM_LIST[1];
00229 H5_DLLVAR const H5B2_class_t H5SM_INDEX[1];
00230 
00231 /****************************/
00232 /* Package Prototypes       */
00233 /****************************/
00234 
00235 /* General routines */
00236 H5_DLL ssize_t H5SM_get_index(const H5SM_master_table_t *table, unsigned type_id);
00237 
00238 /* Encode and decode routines, used for B-tree and cache encoding/decoding */
00239 H5_DLL herr_t H5SM_message_encode(const H5F_t *f, uint8_t *raw,
00240     const void *native);
00241 H5_DLL herr_t H5SM_message_decode(const H5F_t *f, const uint8_t *raw,
00242     void *native);
00243 
00244 /* Callbacks to give to B-tree traversals */
00245 /* H5SM_message_compare is in H5SMbtree2.c, but is also used by list code
00246  * in H5SM.c.
00247  */
00248 H5_DLL herr_t H5SM_message_compare(const void *rec1,
00249                                    const void *rec2);
00250 
00251 /* H5B2_remove_t callback to add messages to a list index */
00252 H5_DLL herr_t H5SM_btree_convert_to_list_op(const void * record, void *op_data);
00253 
00254 /* Fractal heap 'op' callback to compute hash value for message "in place" */
00255 H5_DLL herr_t H5SM_get_hash_fh_cb(const void *obj, size_t obj_len, void *_udata);
00256 
00257 /* Testing functions */
00258 #ifdef H5SM_TESTING
00259 H5_DLL herr_t H5SM_get_mesg_count_test(H5F_t *f, hid_t dxpl_id, unsigned type_id,
00260     size_t *mesg_count);
00261 #endif /* H5SM_TESTING */
00262 
00263 #endif /* _H5SMpkg_H */
00264