contrib/subversion/subversion/libsvn_fs_x/index.h

   1 /* index.h : interface to FSX indexing functionality
   2  *
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  */
  22
  23 #ifndef SVN_LIBSVN_FS__INDEX_H
  24 #define SVN_LIBSVN_FS__INDEX_H
  25
  26 #include "fs.h"
  27 #include "rev_file.h"
  28
  29 /* Per-defined item index values.  They are used to identify empty or
  30  * mandatory items.
  31  */
  32 #define SVN_FS_X__ITEM_INDEX_UNUSED     0  /* invalid / reserved value */
  33 #define SVN_FS_X__ITEM_INDEX_CHANGES    1  /* list of changed paths */
  34 #define SVN_FS_X__ITEM_INDEX_ROOT_NODE  2  /* the root noderev */
  35 #define SVN_FS_X__ITEM_INDEX_FIRST_USER 3  /* first noderev to be freely
  36                                                assigned */
  37
  38 /* Data / item types as stored in the phys-to-log index.
  39  */
  40 #define SVN_FS_X__ITEM_TYPE_UNUSED     0  /* file section not used */
  41 #define SVN_FS_X__ITEM_TYPE_FILE_REP   1  /* item is a file representation */
  42 #define SVN_FS_X__ITEM_TYPE_DIR_REP    2  /* item is a directory rep. */
  43 #define SVN_FS_X__ITEM_TYPE_FILE_PROPS 3  /* item is a file property rep. */
  44 #define SVN_FS_X__ITEM_TYPE_DIR_PROPS  4  /* item is a directory prop rep */
  45 #define SVN_FS_X__ITEM_TYPE_NODEREV    5  /* item is a noderev */
  46 #define SVN_FS_X__ITEM_TYPE_CHANGES    6  /* item is a changed paths list */
  47
  48 #define SVN_FS_X__ITEM_TYPE_ANY_REP    7  /* item is any representation.
  49                                               Only used in pre-format7. */
  50
  51 #define SVN_FS_X__ITEM_TYPE_CHANGES_CONT  8  /* item is a changes container */
  52 #define SVN_FS_X__ITEM_TYPE_NODEREVS_CONT 9  /* item is a noderevs container */
  53 #define SVN_FS_X__ITEM_TYPE_REPS_CONT    10  /* item is a representations
  54                                                  container */
  55
  56 /* (user visible) entry in the phys-to-log index.  It describes a section
  57  * of some packed / non-packed rev file as containing a specific item.
  58  * There must be no overlapping / conflicting entries.
  59  */
  60 typedef struct svn_fs_x__p2l_entry_t
  61 {
  62   /* offset of the first byte that belongs to the item */
  63   apr_off_t offset;
  64
  65   /* length of the item in bytes */
  66   apr_off_t size;
  67
  68   /* type of the item (see SVN_FS_X__ITEM_TYPE_*) defines */
  69   apr_uint32_t type;
  70
  71   /* modified FNV-1a checksum.  0 if unknown checksum */
  72   apr_uint32_t fnv1_checksum;
  73
  74   /* Number of items in this block / container.  Their list can be found
  75    * in *ITEMS.  0 for unused sections.  1 for non-container items,
  76    * > 1 for containers. */
  77   apr_uint32_t item_count;
  78
  79   /* List of items in that block / container */
  80   svn_fs_x__id_t *items;
  81 } svn_fs_x__p2l_entry_t;
  82
  83 /* Return a (deep) copy of ENTRY, allocated in RESULT_POOL.
  84  */
  85 svn_fs_x__p2l_entry_t *
  86 svn_fs_x__p2l_entry_dup(const svn_fs_x__p2l_entry_t *entry,
  87                         apr_pool_t *result_pool);
  88
  89 /* Open / create a log-to-phys index file with the full file path name
  90  * FILE_NAME.  Return the open file in *PROTO_INDEX allocated in
  91  * RESULT_POOL.
  92  */
  93 svn_error_t *
  94 svn_fs_x__l2p_proto_index_open(apr_file_t **proto_index,
  95                                const char *file_name,
  96                                apr_pool_t *result_pool);
  97
  98 /* Call this function before adding entries for the next revision to the
  99  * log-to-phys index file in PROTO_INDEX.  Use SCRATCH_POOL for temporary
 100  * allocations.
 101  */
 102 svn_error_t *
 103 svn_fs_x__l2p_proto_index_add_revision(apr_file_t *proto_index,
 104                                        apr_pool_t *scratch_pool);
 105
 106 /* Add a new mapping, ITEM_INDEX to the (OFFSET, SUB_ITEM) pair, to log-to-
 107  * phys index file in PROTO_INDEX.  Please note that mappings may be added
 108  * in any order but duplicate entries for the same ITEM_INDEX, SUB_ITEM
 109  * are not supported.  Not all possible index values need to be used.
 110  * (OFFSET, SUB_ITEM) may be (-1, 0) to mark 'invalid' item indexes but
 111  * that is already implied for all item indexes not explicitly given a
 112  * mapping.
 113  *
 114  * Use SCRATCH_POOL for temporary allocations.
 115  */
 116 svn_error_t *
 117 svn_fs_x__l2p_proto_index_add_entry(apr_file_t *proto_index,
 118                                     apr_off_t offset,
 119                                     apr_uint32_t sub_item,
 120                                     apr_uint64_t item_index,
 121                                     apr_pool_t *scratch_pool);
 122
 123 /* Use the proto index file stored at PROTO_FILE_NAME, construct the final
 124  * log-to-phys index and append it to INDEX_FILE.  The first revision will
 125  * be REVISION, entries to the next revision will be assigned to REVISION+1
 126  * and so forth.
 127  *
 128  * Return the MD5 checksum of the on-disk index data in *CHECKSUM, allocated
 129  * in RESULT_POOL.  Use SCRATCH_POOL for temporary allocations.
 130  */
 131 svn_error_t *
 132 svn_fs_x__l2p_index_append(svn_checksum_t **checksum,
 133                            svn_fs_t *fs,
 134                            apr_file_t *index_file,
 135                            const char *proto_file_name,
 136                            svn_revnum_t revision,
 137                            apr_pool_t *result_pool,
 138                            apr_pool_t *scratch_pool);
 139
 140 /* Open / create a phys-to-log index file with the full file path name
 141  * FILE_NAME.  Return the open file in *PROTO_INDEX allocated in
 142  * RESULT_POOL.
 143  */
 144 svn_error_t *
 145 svn_fs_x__p2l_proto_index_open(apr_file_t **proto_index,
 146                                const char *file_name,
 147                                apr_pool_t *result_pool);
 148
 149 /* Add a new mapping ENTRY to the phys-to-log index file in PROTO_INDEX.
 150  * The entries must be added in ascending offset order and must not leave
 151  * intermittent ranges uncovered.  The revision value in ENTRY may be
 152  * SVN_INVALID_REVISION.  Use SCRATCH_POOL for temporary allocations.
 153  */
 154 svn_error_t *
 155 svn_fs_x__p2l_proto_index_add_entry(apr_file_t *proto_index,
 156                                     const svn_fs_x__p2l_entry_t *entry,
 157                                     apr_pool_t *scratch_pool);
 158
 159 /* Set *NEXT_OFFSET to the first offset behind the last entry in the
 160  * phys-to-log proto index file PROTO_INDEX.  This will be 0 for empty
 161  * index files.  Use SCRATCH_POOL for temporary allocations.
 162  */
 163 svn_error_t *
 164 svn_fs_x__p2l_proto_index_next_offset(apr_off_t *next_offset,
 165                                       apr_file_t *proto_index,
 166                                       apr_pool_t *scratch_pool);
 167
 168 /* Use the proto index file stored at PROTO_FILE_NAME, construct the final
 169  * phys-to-log index and append it to INDEX_FILE.  Entries without a valid
 170  * revision will be assigned to the REVISION given here.
 171  *
 172  * Return the MD5 checksum of the on-disk index data in *CHECKSUM, allocated
 173  * in RESULT_POOL.  Use SCRATCH_POOL for temporary allocations.
 174  */
 175 svn_error_t *
 176 svn_fs_x__p2l_index_append(svn_checksum_t **checksum,
 177                            svn_fs_t *fs,
 178                            apr_file_t *index_file,
 179                            const char *proto_file_name,
 180                            svn_revnum_t revision,
 181                            apr_pool_t *result_pool,
 182                            apr_pool_t *scratch_pool);
 183
 184 /* Use the phys-to-log mapping files in FS to build a list of entries
 185  * that (at least partly) overlap with the range given by BLOCK_START
 186  * offset and BLOCK_SIZE in the rep / pack file containing REVISION.
 187  * Return the array in *ENTRIES with svn_fs_fs__p2l_entry_t as elements,
 188  * allocated in RESULT_POOL.  REV_FILE determines whether to access single
 189  * rev or pack file data.  If that is not available anymore (neither in
 190  * cache nor on disk), return an error.  Use SCRATCH_POOL for temporary
 191  * allocations.
 192  *
 193  * Note that (only) the first and the last mapping may cross a cluster
 194  * boundary.
 195  */
 196 svn_error_t *
 197 svn_fs_x__p2l_index_lookup(apr_array_header_t **entries,
 198                            svn_fs_t *fs,
 199                            svn_fs_x__revision_file_t *rev_file,
 200                            svn_revnum_t revision,
 201                            apr_off_t block_start,
 202                            apr_off_t block_size,
 203                            apr_pool_t *result_pool,
 204                            apr_pool_t *scratch_pool);
 205
 206 /* Use the phys-to-log mapping files in FS to return the entry for the
 207  * container or single item starting at global OFFSET in the rep file
 208  * containing REVISION in*ENTRY, allocated in RESULT_POOL.  Sets *ENTRY
 209  * to NULL if no item starts at exactly that offset.  REV_FILE determines
 210  * whether to access single rev or pack file data.  If that is not available
 211  * anymore (neither in cache nor on disk), return an error.
 212  * Use SCRATCH_POOL for temporary allocations.
 213  */
 214 svn_error_t *
 215 svn_fs_x__p2l_entry_lookup(svn_fs_x__p2l_entry_t **entry,
 216                            svn_fs_t *fs,
 217                            svn_fs_x__revision_file_t *rev_file,
 218                            svn_revnum_t revision,
 219                            apr_off_t offset,
 220                            apr_pool_t *result_pool,
 221                            apr_pool_t *scratch_pool);
 222
 223 /* Use the phys-to-log mapping files in FS to return the svn_fs_x__id_t
 224  * for the SUB_ITEM of the container starting at global OFFSET in the rep /
 225  * pack file containing REVISION in *ITEM, allocated in RESULT_POOL.  Sets
 226  * *ITEM to NULL if no element starts at exactly that offset or if it
 227  * contains no more than SUB_ITEM sub-items.
 228  *
 229  * Use SCRATCH_POOL for temporary allocations.
 230  */
 231 svn_error_t *
 232 svn_fs_x__p2l_item_lookup(svn_fs_x__id_t **item,
 233                           svn_fs_t *fs,
 234                           svn_fs_x__revision_file_t *rev_file,
 235                           svn_revnum_t revision,
 236                           apr_off_t offset,
 237                           apr_uint32_t sub_item,
 238                           apr_pool_t *result_pool,
 239                           apr_pool_t *scratch_pool);
 240
 241 /* For ITEM_ID in FS, return the position in the respective rev or pack file
 242  * in *ABSOLUTE_POSITION and the *SUB_ITEM number within the object at that
 243  * location. *SUB_ITEM will be 0 for non-container items.
 244  *
 245  * REV_FILE determines whether to access single rev or pack file data.
 246  * If that is not available anymore (neither in cache nor on disk), re-open
 247  * the rev / pack file and retry to open the index file.  For transaction
 248  * content, REV_FILE may be NULL.
 249  *
 250  * Use SCRATCH_POOL for temporary allocations.
 251  */
 252 svn_error_t *
 253 svn_fs_x__item_offset(apr_off_t *absolute_position,
 254                       apr_uint32_t *sub_item,
 255                       svn_fs_t *fs,
 256                       svn_fs_x__revision_file_t *rev_file,
 257                       const svn_fs_x__id_t *item_id,
 258                       apr_pool_t *scratch_pool);
 259
 260 /* Use the log-to-phys indexes in FS to determine the maximum item indexes
 261  * assigned to revision START_REV to START_REV + COUNT - 1.  That is a
 262  * close upper limit to the actual number of items in the respective revs.
 263  * Return the results in *MAX_IDS,  allocated in RESULT_POOL.
 264  * Use SCRATCH_POOL for temporary allocations.
 265  */
 266 svn_error_t *
 267 svn_fs_x__l2p_get_max_ids(apr_array_header_t **max_ids,
 268                           svn_fs_t *fs,
 269                           svn_revnum_t start_rev,
 270                           apr_size_t count,
 271                           apr_pool_t *result_pool,
 272                           apr_pool_t *scratch_pool);
 273
 274 /* In *OFFSET, return the first OFFSET in the pack / rev file containing
 275  * REVISION in FS not covered by the log-to-phys index.
 276  * Use SCRATCH_POOL for temporary allocations.
 277  */
 278 svn_error_t *
 279 svn_fs_x__p2l_get_max_offset(apr_off_t *offset,
 280                              svn_fs_t *fs,
 281                              svn_fs_x__revision_file_t *rev_file,
 282                              svn_revnum_t revision,
 283                              apr_pool_t *scratch_pool);
 284
 285 /* Index (re-)creation utilities.
 286  */
 287
 288 /* For FS, create a new L2P auto-deleting proto index file in POOL and return
 289  * its name in *PROTONAME.  All entries to write are given in ENTRIES and
 290  * entries are of type svn_fs_fs__p2l_entry_t* (sic!).  The ENTRIES array
 291  * will be reordered.  Give the proto index file the lifetime of RESULT_POOL
 292  * and use SCRATCH_POOL for temporary allocations.
 293  */
 294 svn_error_t *
 295 svn_fs_x__l2p_index_from_p2l_entries(const char **protoname,
 296                                      svn_fs_t *fs,
 297                                      apr_array_header_t *entries,
 298                                      apr_pool_t *result_pool,
 299                                      apr_pool_t *scratch_pool);
 300
 301 /* For FS, create a new P2L auto-deleting proto index file in POOL and return
 302  * its name in *PROTONAME.  All entries to write are given in ENTRIES and
 303  * of type svn_fs_fs__p2l_entry_t*.  The FVN1 checksums are not taken from
 304  * ENTRIES but are begin calculated from the current contents of REV_FILE
 305  * as we go.  Give the proto index file the lifetime of RESULT_POOL and use
 306  * SCRATCH_POOL for temporary allocations.
 307  */
 308 svn_error_t *
 309 svn_fs_x__p2l_index_from_p2l_entries(const char **protoname,
 310                                      svn_fs_t *fs,
 311                                      svn_fs_x__revision_file_t *rev_file,
 312                                      apr_array_header_t *entries,
 313                                      apr_pool_t *result_pool,
 314                                      apr_pool_t *scratch_pool);
 315
 316 /* Serialization and caching interface
 317  */
 318
 319 /* We use this key type to address individual pages from both index types.
 320  */
 321 typedef struct svn_fs_x__page_cache_key_t
 322 {
 323   /* in l2p: this is the revision of the items being mapped
 324      in p2l: this is the start revision identifying the pack / rev file */
 325   apr_uint32_t revision;
 326
 327   /* if TRUE, this is the index to a pack file
 328    */
 329   svn_boolean_t is_packed;
 330
 331   /* in l2p: page number within the revision
 332    * in p2l: page number with the rev / pack file
 333    */
 334   apr_uint64_t page;
 335 } svn_fs_x__page_cache_key_t;
 336
 337 /*
 338  * Implements svn_cache__serialize_func_t for l2p_header_t objects.
 339  */
 340 svn_error_t *
 341 svn_fs_x__serialize_l2p_header(void **data,
 342                                apr_size_t *data_len,
 343                                void *in,
 344                                apr_pool_t *pool);
 345
 346 /*
 347  * Implements svn_cache__deserialize_func_t for l2p_header_t objects.
 348  */
 349 svn_error_t *
 350 svn_fs_x__deserialize_l2p_header(void **out,
 351                                  void *data,
 352                                  apr_size_t data_len,
 353                                  apr_pool_t *pool);
 354
 355 /*
 356  * Implements svn_cache__serialize_func_t for l2p_page_t objects.
 357  */
 358 svn_error_t *
 359 svn_fs_x__serialize_l2p_page(void **data,
 360                              apr_size_t *data_len,
 361                              void *in,
 362                              apr_pool_t *pool);
 363
 364 /*
 365  * Implements svn_cache__deserialize_func_t for l2p_page_t objects.
 366  */
 367 svn_error_t *
 368 svn_fs_x__deserialize_l2p_page(void **out,
 369                                void *data,
 370                                apr_size_t data_len,
 371                                apr_pool_t *pool);
 372
 373 /*
 374  * Implements svn_cache__serialize_func_t for p2l_header_t objects.
 375  */
 376 svn_error_t *
 377 svn_fs_x__serialize_p2l_header(void **data,
 378                                apr_size_t *data_len,
 379                                void *in,
 380                                apr_pool_t *pool);
 381
 382 /*
 383  * Implements svn_cache__deserialize_func_t for p2l_header_t objects.
 384  */
 385 svn_error_t *
 386 svn_fs_x__deserialize_p2l_header(void **out,
 387                                  void *data,
 388                                  apr_size_t data_len,
 389                                  apr_pool_t *pool);
 390
 391 /*
 392  * Implements svn_cache__serialize_func_t for apr_array_header_t objects
 393  * with elements of type svn_fs_x__p2l_entry_t.
 394  */
 395 svn_error_t *
 396 svn_fs_x__serialize_p2l_page(void **data,
 397                              apr_size_t *data_len,
 398                              void *in,
 399                              apr_pool_t *pool);
 400
 401 /*
 402  * Implements svn_cache__deserialize_func_t for apr_array_header_t objects
 403  * with elements of type svn_fs_x__p2l_entry_t.
 404  */
 405 svn_error_t *
 406 svn_fs_x__deserialize_p2l_page(void **out,
 407                                void *data,
 408                                apr_size_t data_len,
 409                                apr_pool_t *pool);
 410
 411 #endif