1 /* reps.h --- FSX representation container
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_X_REPS_H
24 #define SVN_LIBSVN_FS_X_REPS_H
29 /* This container type implements the start-delta (aka pick lists) data
30 * structure plus functions to create it and read data from it. The key
31 * point is to identify common sub-strings within a whole set of fulltexts
32 * instead of only two as in the classic txdelta code.
34 * Because it is relatively expensive to optimize the final in-memory
35 * layout, representation containers cannot be updated. A builder object
36 * will do most of the space saving when adding fulltexts but the final
37 * data will only be created immediately before serializing everything to
38 * disk. So, builders are write only and representation containers are
41 * Extracting data from a representation container is O(length) but it
42 * may require multiple iterations if base representations outside the
43 * container were used. Therefore, you will first create an extractor
44 * object (this may happen while holding a cache lock) and the you need
45 * to "drive" the extractor outside any cache context.
48 /* A write-only constructor object for representation containers.
50 typedef struct svn_fs_x__reps_builder_t svn_fs_x__reps_builder_t;
52 /* A read-only representation container -
53 * an opaque collection of fulltexts, i.e. byte strings.
55 typedef struct svn_fs_x__reps_t svn_fs_x__reps_t;
57 /* The fulltext extractor utility object.
59 typedef struct svn_fs_x__rep_extractor_t svn_fs_x__rep_extractor_t;
61 /* Baton type to be passed to svn_fs_x__reps_get_func.
63 typedef struct svn_fs_x__reps_baton_t
65 /* filesystem the resulting extractor shall operate on */
68 /* element index of the item to extract from the container */
70 } svn_fs_x__reps_baton_t;
72 /* Create and populate noderev containers. */
74 /* Create and return a new builder object, allocated in RESULT_POOL.
76 svn_fs_x__reps_builder_t *
77 svn_fs_x__reps_builder_create(svn_fs_t *fs,
78 apr_pool_t *result_pool);
80 /* To BUILDER, add reference to the fulltext currently stored in
81 * representation REP. Substrings matching with any of the base reps
82 * in BUILDER can be removed from the text base and be replaced by
83 * references to those base representations.
85 * The PRIORITY is a mere hint on which base representations should
86 * preferred in case we could re-use the same contents from multiple bases.
87 * Higher numerical value means higher priority / likelihood of being
88 * selected over others.
90 * Use SCRATCH_POOL for temporary allocations.
93 svn_fs_x__reps_add_base(svn_fs_x__reps_builder_t *builder,
94 svn_fs_x__representation_t *rep,
96 apr_pool_t *scratch_pool);
98 /* Add the byte string CONTENTS to BUILDER. Return the item index under
99 * which the fulltext can be retrieved from the final container in *REP_IDX.
102 svn_fs_x__reps_add(apr_size_t *rep_idx,
103 svn_fs_x__reps_builder_t *builder,
104 const svn_string_t *contents);
106 /* Return a rough estimate in bytes for the serialized representation
110 svn_fs_x__reps_estimate_size(const svn_fs_x__reps_builder_t *builder);
112 /* Read from representation containers. */
114 /* For fulltext IDX in CONTAINER in filesystem FS, create an extract object
115 * allocated in RESULT_POOL and return it in *EXTRACTOR.
118 svn_fs_x__reps_get(svn_fs_x__rep_extractor_t **extractor,
120 const svn_fs_x__reps_t *container,
122 apr_pool_t *result_pool);
124 /* Let the EXTRACTOR object fetch all parts of the desired fulltext and
125 * return the latter in *CONTENTS. If SIZE is not 0, return SIZE bytes
126 * starting at offset START_OFFSET of the full contents. If that range
127 * lies partly or completely outside the content, clip it accordingly.
128 * Allocate the result in RESULT_POOL and use SCRATCH_POOL for temporary
131 * Note, you may not run this inside a cache access function.
134 svn_fs_x__extractor_drive(svn_stringbuf_t** contents,
135 svn_fs_x__rep_extractor_t* extractor,
136 apr_size_t start_offset,
138 apr_pool_t* result_pool,
139 apr_pool_t* scratch_pool);
143 /* Write a serialized representation of the final container described by
144 * BUILDER to STREAM. Use SCRATCH_POOL for temporary allocations.
147 svn_fs_x__write_reps_container(svn_stream_t *stream,
148 const svn_fs_x__reps_builder_t *builder,
149 apr_pool_t *scratch_pool);
151 /* Read a representations container from its serialized representation in
152 * STREAM. Allocate the result in RESULT_POOL and return it in *CONTAINER.
153 * Use SCRATCH_POOL for temporary allocations.
156 svn_fs_x__read_reps_container(svn_fs_x__reps_t **container,
157 svn_stream_t *stream,
158 apr_pool_t *result_pool,
159 apr_pool_t *scratch_pool);
161 /* Implements #svn_cache__serialize_func_t for svn_fs_x__reps_t objects.
164 svn_fs_x__serialize_reps_container(void **data,
165 apr_size_t *data_len,
169 /* Implements #svn_cache__deserialize_func_t for svn_fs_x__reps_t objects.
172 svn_fs_x__deserialize_reps_container(void **out,
175 apr_pool_t *result_pool);
177 /* Implements svn_cache__partial_getter_func_t for svn_fs_x__reps_t,
178 * setting *OUT to an svn_fs_x__rep_extractor_t object defined by the
179 * svn_fs_x__reps_baton_t passed in as *BATON. This function is similar
180 * to svn_fs_x__reps_get but operates on the cache serialized
181 * representation of the container.
184 svn_fs_x__reps_get_func(void **out,