contrib/subversion/subversion/libsvn_fs_x/reps.h

   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__REPS_H
  24 #define SVN_LIBSVN_FS__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  */
  50 typedef 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  */
  55 typedef struct svn_fs_x__reps_t svn_fs_x__reps_t;
  56
  57 /* The fulltext extractor utility object.
  58  */
  59 typedef 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  */
  63 typedef 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  */
  76 svn_fs_x__reps_builder_t *
  77 svn_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  */
  92 svn_error_t *
  93 svn_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  */
 101 svn_error_t *
 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);
 105
 106 /* Return a rough estimate in bytes for the serialized representation
 107  * of BUILDER.
 108  */
 109 apr_size_t
 110 svn_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 POOL and return it in *EXTRACTOR.
 116  */
 117 svn_error_t *
 118 svn_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 *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  */
 133 svn_error_t *
 134 svn_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  */
 146 svn_error_t *
 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);
 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  */
 155 svn_error_t *
 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);
 160
 161 /* Implements #svn_cache__serialize_func_t for svn_fs_x__reps_t objects.
 162  */
 163 svn_error_t *
 164 svn_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  */
 171 svn_error_t *
 172 svn_fs_x__deserialize_reps_container(void **out,
 173                                      void *data,
 174                                      apr_size_t data_len,
 175                                      apr_pool_t *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  */
 183 svn_error_t *
 184 svn_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