contrib/subversion/subversion/libsvn_fs_fs/index.h

   1 /* index.h : interface to FSFS 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_FS__ITEM_INDEX_UNUSED     0  /* invalid / reserved value */
  33 #define SVN_FS_FS__ITEM_INDEX_CHANGES    1  /* list of changed paths */
  34 #define SVN_FS_FS__ITEM_INDEX_ROOT_NODE  2  /* the root noderev */
  35 #define SVN_FS_FS__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_FS__ITEM_TYPE_UNUSED     0  /* file section not used */
  41 #define SVN_FS_FS__ITEM_TYPE_FILE_REP   1  /* item is a file representation */
  42 #define SVN_FS_FS__ITEM_TYPE_DIR_REP    2  /* item is a directory rep. */
  43 #define SVN_FS_FS__ITEM_TYPE_FILE_PROPS 3  /* item is a file property rep. */
  44 #define SVN_FS_FS__ITEM_TYPE_DIR_PROPS  4  /* item is a directory prop rep */
  45 #define SVN_FS_FS__ITEM_TYPE_NODEREV    5  /* item is a noderev */
  46 #define SVN_FS_FS__ITEM_TYPE_CHANGES    6  /* item is a changed paths list */
  47
  48 #define SVN_FS_FS__ITEM_TYPE_ANY_REP    7  /* item is any representation.
  49                                               Only used in pre-format7. */
  50
  51 /* Open / create a log-to-phys index file with the full file path name
  52  * FILE_NAME.  Return the open file in *PROTO_INDEX allocated in
  53  * RESULT_POOL.
  54  */
  55 svn_error_t *
  56 svn_fs_fs__l2p_proto_index_open(apr_file_t **proto_index,
  57                                 const char *file_name,
  58                                 apr_pool_t *result_pool);
  59
  60 /* Call this function before adding entries for the next revision to the
  61  * log-to-phys index file in PROTO_INDEX.  Use SCRATCH_POOL for temporary
  62  * allocations.
  63  */
  64 svn_error_t *
  65 svn_fs_fs__l2p_proto_index_add_revision(apr_file_t *proto_index,
  66                                         apr_pool_t *scratch_pool);
  67
  68 /* Add a new mapping, ITEM_INDEX to the OFFSET, to log-to-phys index file
  69  * in PROTO_INDEX.  Please note that mappings may be added in any order
  70  * but duplicate entries for the same ITEM_INDEX are not supported.
  71  * Not all possible index values need to be used.  OFFSET may be -1 to
  72  * mark 'invalid' item indexes but that is already implied for all item
  73  * indexes not explicitly given a mapping.
  74  *
  75  * Use SCRATCH_POOL for temporary allocations.
  76  */
  77 svn_error_t *
  78 svn_fs_fs__l2p_proto_index_add_entry(apr_file_t *proto_index,
  79                                      apr_off_t offset,
  80                                      apr_uint64_t item_index,
  81                                      apr_pool_t *scratch_pool);
  82
  83 /* Use the proto index file stored at PROTO_FILE_NAME, construct the final
  84  * log-to-phys index and append it to INDEX_FILE.  The first revision will
  85  * be REVISION, entries to the next revision will be assigned to REVISION+1
  86  * and so forth.
  87  *
  88  * Return the MD5 checksum of the on-disk index data in *CHECKSUM, allocated
  89  * in RESULT_POOL.  Use SCRATCH_POOL for temporary allocations.
  90  */
  91 svn_error_t *
  92 svn_fs_fs__l2p_index_append(svn_checksum_t **checksum,
  93                             svn_fs_t *fs,
  94                             apr_file_t *index_file,
  95                             const char *proto_file_name,
  96                             svn_revnum_t revision,
  97                             apr_pool_t *result_pool,
  98                             apr_pool_t *scratch_pool);
  99
 100 /* Open / create a phys-to-log index file with the full file path name
 101  * FILE_NAME.  Return the open file in *PROTO_INDEX allocated in
 102  * RESULT_POOL.
 103  */
 104 svn_error_t *
 105 svn_fs_fs__p2l_proto_index_open(apr_file_t **proto_index,
 106                                 const char *file_name,
 107                                 apr_pool_t *result_pool);
 108
 109 /* Add a new mapping ENTRY to the phys-to-log index file in PROTO_INDEX.
 110  * The entries must be added in ascending offset order and must not leave
 111  * intermittent ranges uncovered.  The revision value in ENTRY may be
 112  * SVN_INVALID_REVISION.  Use SCRATCH_POOL for temporary allocations.
 113  */
 114 svn_error_t *
 115 svn_fs_fs__p2l_proto_index_add_entry(apr_file_t *proto_index,
 116                                      const svn_fs_fs__p2l_entry_t *entry,
 117                                      apr_pool_t *scratch_pool);
 118
 119 /* Set *NEXT_OFFSET to the first offset behind the last entry in the
 120  * phys-to-log proto index file PROTO_INDEX.  This will be 0 for empty
 121  * index files.  Use SCRATCH_POOL for temporary allocations.
 122  */
 123 svn_error_t *
 124 svn_fs_fs__p2l_proto_index_next_offset(apr_off_t *next_offset,
 125                                        apr_file_t *proto_index,
 126                                        apr_pool_t *scratch_pool);
 127
 128 /* Use the proto index file stored at PROTO_FILE_NAME, construct the final
 129  * phys-to-log index and append it to INDEX_FILE.  Entries without a valid
 130  * revision will be assigned to the REVISION given here.
 131  *
 132  * Return the MD5 checksum of the on-disk index data in *CHECKSUM, allocated
 133  * in RESULT_POOL.  Use SCRATCH_POOL for temporary allocations.
 134  */
 135 svn_error_t *
 136 svn_fs_fs__p2l_index_append(svn_checksum_t **checksum,
 137                             svn_fs_t *fs,
 138                             apr_file_t *index_file,
 139                             const char *proto_file_name,
 140                             svn_revnum_t revision,
 141                             apr_pool_t *result_pool,
 142                             apr_pool_t *scratch_pool);
 143
 144 /* Use the phys-to-log mapping files in FS to build a list of entries
 145  * that (at least partly) overlap with the range given by BLOCK_START
 146  * offset and BLOCK_SIZE in the rep / pack file containing REVISION.
 147  * Return the array in *ENTRIES with svn_fs_fs__p2l_entry_t as elements,
 148  * allocated in RESULT_POOL.  REV_FILE determines whether to access single
 149  * rev or pack file data.  If that is not available anymore (neither in
 150  * cache nor on disk), return an error.  Use SCRATCH_POOL for temporary
 151  * allocations.
 152  *
 153  * Note that (only) the first and the last mapping may cross a cluster
 154  * boundary.
 155  */
 156 svn_error_t *
 157 svn_fs_fs__p2l_index_lookup(apr_array_header_t **entries,
 158                             svn_fs_t *fs,
 159                             svn_fs_fs__revision_file_t *rev_file,
 160                             svn_revnum_t revision,
 161                             apr_off_t block_start,
 162                             apr_off_t block_size,
 163                             apr_pool_t *result_pool,
 164                             apr_pool_t *scratch_pool);
 165
 166 /* Use the phys-to-log mapping files in FS to return the entry for the
 167  * item starting at global OFFSET in the rep file containing REVISION in
 168  * *ENTRY, allocated in RESULT_POOL.  Sets *ENTRY to NULL if no item starts
 169  * at exactly that offset.  REV_FILE determines whether to access single
 170  * rev or pack file data.  If that is not available anymore (neither in
 171  * cache nor on disk), return an error.  Use SCRATCH_POOL for temporary
 172  * allocations.
 173  */
 174 svn_error_t *
 175 svn_fs_fs__p2l_entry_lookup(svn_fs_fs__p2l_entry_t **entry,
 176                             svn_fs_t *fs,
 177                             svn_fs_fs__revision_file_t *rev_file,
 178                             svn_revnum_t revision,
 179                             apr_off_t offset,
 180                             apr_pool_t *result_pool,
 181                             apr_pool_t *scratch_pool);
 182
 183 /* For ITEM_INDEX within REV in FS, return the position in the respective
 184  * rev or pack file in *ABSOLUTE_POSITION.  If TXN_ID is not NULL, return
 185  * the file offset within that transaction and REV should be given as
 186  * SVN_INVALID_REVNUM in that case.
 187  *
 188  * REV_FILE determines whether to access single rev or pack file data.
 189  * If that is not available anymore (neither in cache nor on disk), re-open
 190  * the rev / pack file and retry to open the index file.  For anything but
 191  * committed log addressed revisions, REV_FILE may be NULL.
 192  * Use SCRATCH_POOL for temporary allocations.
 193  */
 194 svn_error_t *
 195 svn_fs_fs__item_offset(apr_off_t *absolute_position,
 196                        svn_fs_t *fs,
 197                        svn_fs_fs__revision_file_t *rev_file,
 198                        svn_revnum_t revision,
 199                        const svn_fs_fs__id_part_t *txn_id,
 200                        apr_uint64_t item_index,
 201                        apr_pool_t *scratch_pool);
 202
 203 /* Use the log-to-phys indexes in FS to determine the maximum item indexes
 204  * assigned to revision START_REV to START_REV + COUNT - 1.  That is a
 205  * close upper limit to the actual number of items in the respective revs.
 206  * Return the results in *MAX_IDS,  allocated in RESULT_POOL.
 207  * Use SCRATCH_POOL for temporary allocations.
 208  */
 209 svn_error_t *
 210 svn_fs_fs__l2p_get_max_ids(apr_array_header_t **max_ids,
 211                            svn_fs_t *fs,
 212                            svn_revnum_t start_rev,
 213                            apr_size_t count,
 214                            apr_pool_t *result_pool,
 215                            apr_pool_t *scratch_pool);
 216
 217 /* In *OFFSET, return the last OFFSET in the pack / rev file containing.
 218  * REV_FILE determines whether to access single rev or pack file data.
 219  * If that is not available anymore (neither in cache nor on disk), re-open
 220  * the rev / pack file and retry to open the index file.
 221  * Use SCRATCH_POOL for temporary allocations.
 222  */
 223 svn_error_t *
 224 svn_fs_fs__p2l_get_max_offset(apr_off_t *offset,
 225                               svn_fs_t *fs,
 226                               svn_fs_fs__revision_file_t *rev_file,
 227                               svn_revnum_t revision,
 228                               apr_pool_t *scratch_pool);
 229
 230 /* Index (re-)creation utilities.
 231  */
 232
 233 /* For FS, create a new L2P auto-deleting proto index file in POOL and return
 234  * its name in *PROTONAME.  All entries to write are given in ENTRIES and
 235  * entries are of type svn_fs_fs__p2l_entry_t* (sic!).  The ENTRIES array
 236  * will be reordered.  Give the proto index file the lifetime of RESULT_POOL
 237  * and use SCRATCH_POOL for temporary allocations.
 238  */
 239 svn_error_t *
 240 svn_fs_fs__l2p_index_from_p2l_entries(const char **protoname,
 241                                       svn_fs_t *fs,
 242                                       apr_array_header_t *entries,
 243                                       apr_pool_t *result_pool,
 244                                       apr_pool_t *scratch_pool);
 245
 246 /* For FS, create a new P2L auto-deleting proto index file in POOL and return
 247  * its name in *PROTONAME.  All entries to write are given in ENTRIES and
 248  * of type svn_fs_fs__p2l_entry_t*.  The FVN1 checksums are not taken from
 249  * ENTRIES but are begin calculated from the current contents of REV_FILE
 250  * as we go.  Give the proto index file the lifetime of RESULT_POOL and use
 251  * SCRATCH_POOL for temporary allocations.
 252  */
 253 svn_error_t *
 254 svn_fs_fs__p2l_index_from_p2l_entries(const char **protoname,
 255                                       svn_fs_t *fs,
 256                                       svn_fs_fs__revision_file_t *rev_file,
 257                                       apr_array_header_t *entries,
 258                                       apr_pool_t *result_pool,
 259                                       apr_pool_t *scratch_pool);
 260
 261 /* Serialization and caching interface
 262  */
 263
 264 /* We use this key type to address individual pages from both index types.
 265  */
 266 typedef struct svn_fs_fs__page_cache_key_t
 267 {
 268   /* in l2p: this is the revision of the items being mapped
 269      in p2l: this is the start revision identifying the pack / rev file */
 270   apr_uint32_t revision;
 271
 272   /* if TRUE, this is the index to a pack file
 273    */
 274   svn_boolean_t is_packed;
 275
 276   /* in l2p: page number within the revision
 277    * in p2l: page number with the rev / pack file
 278    */
 279   apr_uint64_t page;
 280 } svn_fs_fs__page_cache_key_t;
 281
 282 /*
 283  * Implements svn_cache__serialize_func_t for l2p_header_t objects.
 284  */
 285 svn_error_t *
 286 svn_fs_fs__serialize_l2p_header(void **data,
 287                                 apr_size_t *data_len,
 288                                 void *in,
 289                                 apr_pool_t *pool);
 290
 291 /*
 292  * Implements svn_cache__deserialize_func_t for l2p_header_t objects.
 293  */
 294 svn_error_t *
 295 svn_fs_fs__deserialize_l2p_header(void **out,
 296                                   void *data,
 297                                   apr_size_t data_len,
 298                                   apr_pool_t *pool);
 299
 300 /*
 301  * Implements svn_cache__serialize_func_t for l2p_page_t objects.
 302  */
 303 svn_error_t *
 304 svn_fs_fs__serialize_l2p_page(void **data,
 305                               apr_size_t *data_len,
 306                               void *in,
 307                               apr_pool_t *pool);
 308
 309 /*
 310  * Implements svn_cache__deserialize_func_t for l2p_page_t objects.
 311  */
 312 svn_error_t *
 313 svn_fs_fs__deserialize_l2p_page(void **out,
 314                                 void *data,
 315                                 apr_size_t data_len,
 316                                 apr_pool_t *pool);
 317
 318 /*
 319  * Implements svn_cache__serialize_func_t for p2l_header_t objects.
 320  */
 321 svn_error_t *
 322 svn_fs_fs__serialize_p2l_header(void **data,
 323                                 apr_size_t *data_len,
 324                                 void *in,
 325                                 apr_pool_t *pool);
 326
 327 /*
 328  * Implements svn_cache__deserialize_func_t for p2l_header_t objects.
 329  */
 330 svn_error_t *
 331 svn_fs_fs__deserialize_p2l_header(void **out,
 332                                   void *data,
 333                                   apr_size_t data_len,
 334                                   apr_pool_t *pool);
 335
 336 /*
 337  * Implements svn_cache__serialize_func_t for apr_array_header_t objects
 338  * with elements of type svn_fs_fs__p2l_entry_t.
 339  */
 340 svn_error_t *
 341 svn_fs_fs__serialize_p2l_page(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 apr_array_header_t objects
 348  * with elements of type svn_fs_fs__p2l_entry_t.
 349  */
 350 svn_error_t *
 351 svn_fs_fs__deserialize_p2l_page(void **out,
 352                                 void *data,
 353                                 apr_size_t data_len,
 354                                 apr_pool_t *pool);
 355
 356 #endif