H5Bprivate.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  *
00018  * Created:             H5Bprivate.h
00019  *                      Jul 10 1997
00020  *                      Robb Matzke <matzke@llnl.gov>
00021  *
00022  * Purpose:             Private non-prototype header.
00023  *
00024  * Modifications:
00025  *
00026  *-------------------------------------------------------------------------
00027  */
00028 
00029 #ifndef _H5Bprivate_H
00030 #define _H5Bprivate_H
00031 
00032 #include "H5Bpublic.h"          /*API prototypes                             */
00033 
00034 /* Private headers needed by this file */
00035 #include "H5private.h"          /* Generic Functions                    */
00036 #include "H5Fprivate.h"         /* File access                          */
00037 #include "H5RCprivate.h"        /* Reference counted object functions   */
00038 
00039 /**************************/
00040 /* Library Private Macros */
00041 /**************************/
00042 
00043 /*
00044  * Feature: Define this constant if you want to check B-tree consistency
00045  *          after each B-tree operation.  Note that this slows down the
00046  *          library considerably! Debugging the B-tree depends on assert()
00047  *          being enabled.
00048  */
00049 #ifdef NDEBUG
00050 #  undef H5B_DEBUG
00051 #endif
00052 
00053 
00054 /****************************/
00055 /* Library Private Typedefs */
00056 /****************************/
00057 
00058 /* B-tree IDs for various internal things. */
00059 /* Note - if more of these are added, any 'K' values (for internal or leaf
00060  * nodes) they use will need to be stored in the file somewhere. -QAK
00061  */
00062 typedef enum H5B_subid_t {
00063     H5B_SNODE_ID         = 0,   /*B-tree is for symbol table nodes           */
00064     H5B_CHUNK_ID         = 1,   /*B-tree is for chunked dataset storage      */
00065     H5B_NUM_BTREE_ID            /* Number of B-tree key IDs (must be last)   */
00066 } H5B_subid_t;
00067 
00068 /* Define return values from B-tree insertion callbacks */
00069 typedef enum H5B_ins_t {
00070     H5B_INS_ERROR        = -1,  /*error return value                         */
00071     H5B_INS_NOOP         = 0,   /*insert made no changes                     */
00072     H5B_INS_LEFT         = 1,   /*insert new node to left of cur node        */
00073     H5B_INS_RIGHT        = 2,   /*insert new node to right of cur node       */
00074     H5B_INS_CHANGE       = 3,   /*change child address for cur node          */
00075     H5B_INS_FIRST        = 4,   /*insert first node in (sub)tree             */
00076     H5B_INS_REMOVE       = 5    /*remove current node                        */
00077 } H5B_ins_t;
00078 
00079 /* Enum for specifying the direction of the critical key in relation to the
00080  * child */
00081 typedef enum H5B_dir_t {
00082     H5B_LEFT            = 0,    /* Critical key is to the left */
00083     H5B_RIGHT           = 1     /* Critical key is to the right */
00084 } H5B_dir_t;
00085 
00086 /* Define the operator callback function pointer for H5B_iterate() */
00087 typedef int (*H5B_operator_t)(H5F_t *f, hid_t dxpl_id, const void *_lt_key, haddr_t addr,
00088                                         const void *_rt_key, void *_udata);
00089 
00090 /* Each B-tree has certain information that can be shared across all
00091  * the instances of nodes in that B-tree.
00092  */
00093 typedef struct H5B_shared_t {
00094     const struct H5B_class_t    *type;  /* Type of tree                      */
00095     unsigned            two_k;          /* 2*"K" value for tree's nodes      */
00096     size_t              sizeof_rkey;    /* Size of raw (disk) key            */
00097     size_t              sizeof_rnode;   /* Size of raw (disk) node           */
00098     size_t              sizeof_keys;    /* Size of native (memory) key node  */
00099     size_t              sizeof_addr;    /* Size of file address (in bytes)   */
00100     size_t              sizeof_len;     /* Size of file lengths (in bytes)   */
00101     uint8_t             *page;          /* Disk page */
00102     size_t              *nkey;          /* Offsets of each native key in native key buffer */
00103 } H5B_shared_t;
00104 
00105 /*
00106  * Each class of object that can be pointed to by a B-link tree has a
00107  * variable of this type that contains class variables and methods.  Each
00108  * tree has a K (1/2 rank) value on a per-file basis.  The file_create_parms
00109  * has an array of K values indexed by the `id' class field below.  The
00110  * array is initialized with the HDF5_BTREE_K_DEFAULT macro.
00111  */
00112 
00113 typedef struct H5B_class_t {
00114     H5B_subid_t id;                                     /*id as found in file*/
00115     size_t      sizeof_nkey;                    /*size of native (memory) key*/
00116     H5RC_t *    (*get_shared)(const H5F_t*, const void*);    /*shared info for node */
00117     herr_t      (*new_node)(H5F_t*, hid_t, H5B_ins_t, void*, void*, void*, haddr_t*);
00118     int         (*cmp2)(void*, void*, void*);       /*compare 2 keys */
00119     int         (*cmp3)(void*, void*, void*);       /*compare 3 keys */
00120     htri_t      (*found)(H5F_t*, hid_t, haddr_t, const void*, void*);
00121 
00122     /* insert new data */
00123     H5B_ins_t   (*insert)(H5F_t*, hid_t, haddr_t, void*, hbool_t*, void*, void*,
00124                           void*, hbool_t*, haddr_t*);
00125 
00126     /* min insert uses min leaf, not new(), similarily for max insert */
00127     hbool_t     follow_min;
00128     hbool_t     follow_max;
00129 
00130     /* The direction of the key that is intrinsically associated with each node */
00131     H5B_dir_t   critical_key;
00132 
00133     /* remove existing data */
00134     H5B_ins_t   (*remove)(H5F_t*, hid_t, haddr_t, void*, hbool_t*, void*, void*,
00135                           hbool_t*);
00136 
00137     /* encode, decode, debug key values */
00138     herr_t      (*decode)(const H5B_shared_t*, const uint8_t*, void*);
00139     herr_t      (*encode)(const H5B_shared_t*, uint8_t*, const void*);
00140     herr_t      (*debug_key)(FILE*, int, int, const void*, const void*);
00141 } H5B_class_t;
00142 
00143 /* Information about B-tree */
00144 typedef struct H5B_info_t {
00145     hsize_t     size;           /* Size of B-tree nodes */
00146     hsize_t     num_nodes;      /* Number of B-tree nodes */
00147 } H5B_info_t;
00148 
00149 
00150 
00151 /*****************************/
00152 /* Library-private Variables */
00153 /*****************************/
00154 
00155 
00156 /***************************************/
00157 /* Library-private Function Prototypes */
00158 /***************************************/
00159 H5_DLL herr_t H5B_create(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00160     void *udata, haddr_t *addr_p/*out*/);
00161 H5_DLL herr_t H5B_find(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00162     haddr_t addr, void *udata);
00163 H5_DLL herr_t H5B_insert(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00164     haddr_t addr, void *udata);
00165 H5_DLL herr_t H5B_iterate(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00166     haddr_t addr, H5B_operator_t op, void *udata);
00167 H5_DLL herr_t H5B_get_info(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00168     haddr_t addr, H5B_info_t *bt_info, H5B_operator_t op, void *udata);
00169 H5_DLL herr_t H5B_remove(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00170     haddr_t addr, void *udata);
00171 H5_DLL herr_t H5B_delete(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00172     haddr_t addr, void *udata);
00173 H5_DLL H5B_shared_t *H5B_shared_new(const H5F_t *f, const H5B_class_t *type,
00174     size_t sizeof_rkey);
00175 H5_DLL herr_t H5B_shared_free(void *_shared);
00176 H5_DLL herr_t H5B_debug(H5F_t *f, hid_t dxpl_id, haddr_t addr, FILE * stream,
00177     int indent, int fwidth, const H5B_class_t *type, void *udata);
00178 H5_DLL htri_t H5B_valid(H5F_t *f, hid_t dxpl_id, const H5B_class_t *type,
00179     haddr_t addr);
00180 #endif /* _H5Bprivate_H */
00181