1 /* index.h : interface to FSX indexing functionality
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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
20 * ====================================================================
23 #ifndef SVN_LIBSVN_FS__INDEX_H
24 #define SVN_LIBSVN_FS__INDEX_H
29 /* Per-defined item index values. They are used to identify empty or
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
38 /* Data / item types as stored in the phys-to-log index.
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 */
48 #define SVN_FS_X__ITEM_TYPE_ANY_REP 7 /* item is any representation.
49 Only used in pre-format7. */
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
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.
60 typedef struct svn_fs_x__p2l_entry_t
62 /* offset of the first byte that belongs to the item */
65 /* length of the item in bytes */
68 /* type of the item (see SVN_FS_X__ITEM_TYPE_*) defines */
71 /* modified FNV-1a checksum. 0 if unknown checksum */
72 apr_uint32_t fnv1_checksum;
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;
79 /* List of items in that block / container */
80 svn_fs_x__id_t *items;
81 } svn_fs_x__p2l_entry_t;
83 /* Return a (deep) copy of ENTRY, allocated in RESULT_POOL.
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);
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
94 svn_fs_x__l2p_proto_index_open(apr_file_t **proto_index,
95 const char *file_name,
96 apr_pool_t *result_pool);
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
103 svn_fs_x__l2p_proto_index_add_revision(apr_file_t *proto_index,
104 apr_pool_t *scratch_pool);
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
114 * Use SCRATCH_POOL for temporary allocations.
117 svn_fs_x__l2p_proto_index_add_entry(apr_file_t *proto_index,
119 apr_uint32_t sub_item,
120 apr_uint64_t item_index,
121 apr_pool_t *scratch_pool);
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
128 * Return the MD5 checksum of the on-disk index data in *CHECKSUM, allocated
129 * in RESULT_POOL. Use SCRATCH_POOL for temporary allocations.
132 svn_fs_x__l2p_index_append(svn_checksum_t **checksum,
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);
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
145 svn_fs_x__p2l_proto_index_open(apr_file_t **proto_index,
146 const char *file_name,
147 apr_pool_t *result_pool);
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.
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);
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.
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);
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.
172 * Return the MD5 checksum of the on-disk index data in *CHECKSUM, allocated
173 * in RESULT_POOL. Use SCRATCH_POOL for temporary allocations.
176 svn_fs_x__p2l_index_append(svn_checksum_t **checksum,
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);
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
193 * Note that (only) the first and the last mapping may cross a cluster
197 svn_fs_x__p2l_index_lookup(apr_array_header_t **entries,
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);
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.
215 svn_fs_x__p2l_entry_lookup(svn_fs_x__p2l_entry_t **entry,
217 svn_fs_x__revision_file_t *rev_file,
218 svn_revnum_t revision,
220 apr_pool_t *result_pool,
221 apr_pool_t *scratch_pool);
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.
229 * Use SCRATCH_POOL for temporary allocations.
232 svn_fs_x__p2l_item_lookup(svn_fs_x__id_t **item,
234 svn_fs_x__revision_file_t *rev_file,
235 svn_revnum_t revision,
237 apr_uint32_t sub_item,
238 apr_pool_t *result_pool,
239 apr_pool_t *scratch_pool);
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.
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.
250 * Use SCRATCH_POOL for temporary allocations.
253 svn_fs_x__item_offset(apr_off_t *absolute_position,
254 apr_uint32_t *sub_item,
256 svn_fs_x__revision_file_t *rev_file,
257 const svn_fs_x__id_t *item_id,
258 apr_pool_t *scratch_pool);
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.
267 svn_fs_x__l2p_get_max_ids(apr_array_header_t **max_ids,
269 svn_revnum_t start_rev,
271 apr_pool_t *result_pool,
272 apr_pool_t *scratch_pool);
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.
279 svn_fs_x__p2l_get_max_offset(apr_off_t *offset,
281 svn_fs_x__revision_file_t *rev_file,
282 svn_revnum_t revision,
283 apr_pool_t *scratch_pool);
285 /* Index (re-)creation utilities.
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.
295 svn_fs_x__l2p_index_from_p2l_entries(const char **protoname,
297 apr_array_header_t *entries,
298 apr_pool_t *result_pool,
299 apr_pool_t *scratch_pool);
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.
309 svn_fs_x__p2l_index_from_p2l_entries(const char **protoname,
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);
316 /* Serialization and caching interface
319 /* We use this key type to address individual pages from both index types.
321 typedef struct svn_fs_x__page_cache_key_t
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;
327 /* if TRUE, this is the index to a pack file
329 svn_boolean_t is_packed;
331 /* in l2p: page number within the revision
332 * in p2l: page number with the rev / pack file
335 } svn_fs_x__page_cache_key_t;
338 * Implements svn_cache__serialize_func_t for l2p_header_t objects.
341 svn_fs_x__serialize_l2p_header(void **data,
342 apr_size_t *data_len,
347 * Implements svn_cache__deserialize_func_t for l2p_header_t objects.
350 svn_fs_x__deserialize_l2p_header(void **out,
356 * Implements svn_cache__serialize_func_t for l2p_page_t objects.
359 svn_fs_x__serialize_l2p_page(void **data,
360 apr_size_t *data_len,
365 * Implements svn_cache__deserialize_func_t for l2p_page_t objects.
368 svn_fs_x__deserialize_l2p_page(void **out,
374 * Implements svn_cache__serialize_func_t for p2l_header_t objects.
377 svn_fs_x__serialize_p2l_header(void **data,
378 apr_size_t *data_len,
383 * Implements svn_cache__deserialize_func_t for p2l_header_t objects.
386 svn_fs_x__deserialize_p2l_header(void **out,
392 * Implements svn_cache__serialize_func_t for apr_array_header_t objects
393 * with elements of type svn_fs_x__p2l_entry_t.
396 svn_fs_x__serialize_p2l_page(void **data,
397 apr_size_t *data_len,
402 * Implements svn_cache__deserialize_func_t for apr_array_header_t objects
403 * with elements of type svn_fs_x__p2l_entry_t.
406 svn_fs_x__deserialize_p2l_page(void **out,