1/* reps.h --- FSX representation container
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_X_REPS_H
24#define SVN_LIBSVN_FS_X_REPS_H
25
26#include "svn_io.h"
27#include "fs.h"
28
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.
33 *
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
39 * read-only.
40 *
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.
46 */
47
48/* A write-only constructor object for representation containers.
49 */
50typedef struct svn_fs_x__reps_builder_t svn_fs_x__reps_builder_t;
51
52/* A read-only representation container -
53 * an opaque collection of fulltexts, i.e. byte strings.
54 */
55typedef struct svn_fs_x__reps_t svn_fs_x__reps_t;
56
57/* The fulltext extractor utility object.
58 */
59typedef struct svn_fs_x__rep_extractor_t svn_fs_x__rep_extractor_t;
60
61/* Baton type to be passed to svn_fs_x__reps_get_func.
62 */
63typedef struct svn_fs_x__reps_baton_t
64{
65  /* filesystem the resulting extractor shall operate on */
66  svn_fs_t *fs;
67
68  /* element index of the item to extract from the container */
69  apr_size_t idx;
70} svn_fs_x__reps_baton_t;
71
72/* Create and populate noderev containers. */
73
74/* Create and return a new builder object, allocated in RESULT_POOL.
75 */
76svn_fs_x__reps_builder_t *
77svn_fs_x__reps_builder_create(svn_fs_t *fs,
78                              apr_pool_t *result_pool);
79
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.
84 *
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.
89 *
90 * Use SCRATCH_POOL for temporary allocations.
91 */
92svn_error_t *
93svn_fs_x__reps_add_base(svn_fs_x__reps_builder_t *builder,
94                        svn_fs_x__representation_t *rep,
95                        int priority,
96                        apr_pool_t *scratch_pool);
97
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.
100 */
101svn_error_t *
102svn_fs_x__reps_add(apr_size_t *rep_idx,
103                   svn_fs_x__reps_builder_t *builder,
104                   const svn_string_t *contents);
105
106/* Return a rough estimate in bytes for the serialized representation
107 * of BUILDER.
108 */
109apr_size_t
110svn_fs_x__reps_estimate_size(const svn_fs_x__reps_builder_t *builder);
111
112/* Read from representation containers. */
113
114/* For fulltext IDX in CONTAINER in filesystem FS, create an extract object
115 * allocated in RESULT_POOL and return it in *EXTRACTOR.
116 */
117svn_error_t *
118svn_fs_x__reps_get(svn_fs_x__rep_extractor_t **extractor,
119                   svn_fs_t *fs,
120                   const svn_fs_x__reps_t *container,
121                   apr_size_t idx,
122                   apr_pool_t *result_pool);
123
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
129 * allocations.
130 *
131 * Note, you may not run this inside a cache access function.
132 */
133svn_error_t *
134svn_fs_x__extractor_drive(svn_stringbuf_t** contents,
135                          svn_fs_x__rep_extractor_t* extractor,
136                          apr_size_t start_offset,
137                          apr_size_t size,
138                          apr_pool_t* result_pool,
139                          apr_pool_t* scratch_pool);
140
141/* I/O interface. */
142
143/* Write a serialized representation of the final container described by
144 * BUILDER to STREAM.  Use SCRATCH_POOL for temporary allocations.
145 */
146svn_error_t *
147svn_fs_x__write_reps_container(svn_stream_t *stream,
148                               const svn_fs_x__reps_builder_t *builder,
149                               apr_pool_t *scratch_pool);
150
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.
154 */
155svn_error_t *
156svn_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);
160
161/* Implements #svn_cache__serialize_func_t for svn_fs_x__reps_t objects.
162 */
163svn_error_t *
164svn_fs_x__serialize_reps_container(void **data,
165                                   apr_size_t *data_len,
166                                   void *in,
167                                   apr_pool_t *pool);
168
169/* Implements #svn_cache__deserialize_func_t for svn_fs_x__reps_t objects.
170 */
171svn_error_t *
172svn_fs_x__deserialize_reps_container(void **out,
173                                     void *data,
174                                     apr_size_t data_len,
175                                     apr_pool_t *result_pool);
176
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.
182 */
183svn_error_t *
184svn_fs_x__reps_get_func(void **out,
185                        const void *data,
186                        apr_size_t data_len,
187                        void *baton,
188                        apr_pool_t *pool);
189
190#endif
191