| /* packed_data.h : Interface to the packed binary stream data structure |
| * |
| * ==================================================================== |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * ==================================================================== |
| */ |
| |
| #ifndef SVN_PACKED_DATA_H |
| #define SVN_PACKED_DATA_H |
| |
| #include "svn_string.h" |
| #include "svn_io.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif /* __cplusplus */ |
| |
| /* This API provides Yet Another Serialization Framework. |
| * |
| * It is geared towards efficiently encoding collections of structured |
| * binary data (e.g. an array of noderev objects). The basic idea is to |
| * transform them into hierarchies of streams with each stream usually |
| * corresponding to a single attribute in the original data structures. |
| * The user is free model the mapping structure <-> streams mapping as she |
| * sees fit. |
| * |
| * With all data inside the same (sub-)stream carrying similar attribute |
| * values, the whole stream lends itself to data compression. Strings / |
| * plain byte sequences will be stored as is. Numbers use a 7b/8b encoding |
| * scheme to eliminate leading zeros. Because values are often dependent |
| * (increasing offsets, roughly similar revision number, etc.), streams |
| * can be configured as storing (hopefully shorter) deltas instead of the |
| * original value. |
| * |
| * Two stream types are provided: integer and byte streams. While the |
| * first store 64 bit integers only and can be configured to assume |
| * signed and / or deltifyable data, the second will store arbitrary |
| * byte sequences including their length. At the root level, you may |
| * create an arbitrary number of integer and byte streams. Any stream |
| * may have an arbitrary number of sub-streams of the same kind. You |
| * should create the full stream hierarchy before writing any data to it. |
| * |
| * As a convenience, when an integer stream has sub-streams, you may write |
| * to the parent stream instead of all sub-streams individually and the |
| * values will be passed down automatically in a round-robin fashion. |
| * Reading from the parent stream is similarly supported. |
| * |
| * When all data has been added to the stream, it can be written to an |
| * ordinary svn_stream_t. First, we write a description of the stream |
| * structure (types, sub-streams, sizes and configurations) followed by |
| * zlib compressed stream content. For each top-level stream, all sub- |
| * stream data will be concatenated and then compressed as a single block. |
| * To maximize the effect of this, make sure all data in that stream |
| * hierarchy has a similar value distribution. |
| * |
| * Reading data starts with an svn_stream_t and automatically recreates |
| * the stream hierarchies. You only need to extract data from it in the |
| * same order as you wrote it. |
| * |
| * Although not enforced programmatically, you may either only write to a |
| * stream hierarchy or only read from it but you cannot do both on the |
| * same data structure. |
| */ |
| |
| |
| |
| /* We pack / unpack integers en block to minimize calling and setup overhead. |
| * This is the number of integers we put into a buffer before writing them |
| * them to / after reading them from the 7b/8b stream. Under 64 bits, this |
| * value creates a 128 byte data structure (14 + 2 integers, 8 bytes each). |
| */ |
| #define SVN__PACKED_DATA_BUFFER_SIZE 14 |
| |
| |
| /* Data types. */ |
| |
| /* Opaque type for the root object. |
| */ |
| typedef struct svn_packed__data_root_t svn_packed__data_root_t; |
| |
| /* Opaque type for byte streams. |
| */ |
| typedef struct svn_packed__byte_stream_t svn_packed__byte_stream_t; |
| |
| /* Semi-opaque type for integer streams. We expose the unpacked buffer |
| * to allow for replacing svn_packed__add_uint and friends by macros. |
| */ |
| typedef struct svn_packed__int_stream_t |
| { |
| /* pointer to the remainder of the data structure */ |
| void *private_data; |
| |
| /* number of value entries in BUFFER */ |
| apr_size_t buffer_used; |
| |
| /* unpacked integers (either yet to be packed or pre-fetched from the |
| * packed buffers). Only the first BUFFER_USED entries are valid. */ |
| apr_uint64_t buffer[SVN__PACKED_DATA_BUFFER_SIZE]; |
| } svn_packed__int_stream_t; |
| |
| |
| /* Writing data. */ |
| |
| /* Return a new serialization root object, allocated in POOL. |
| */ |
| svn_packed__data_root_t * |
| svn_packed__data_create_root(apr_pool_t *pool); |
| |
| /* Create and return a new top-level integer stream in ROOT. If signed, |
| * negative numbers will be put into that stream, SIGNED_INTS should be |
| * TRUE as a more efficient encoding will be used in that case. Set |
| * DIFF to TRUE if you expect the difference between consecutive numbers |
| * to be much smaller (~100 times) than the actual numbers. |
| */ |
| svn_packed__int_stream_t * |
| svn_packed__create_int_stream(svn_packed__data_root_t *root, |
| svn_boolean_t diff, |
| svn_boolean_t signed_ints); |
| |
| /* Create and return a sub-stream to the existing integer stream PARENT. |
| * If signed, negative numbers will be put into that stream, SIGNED_INTS |
| * should be TRUE as a more efficient encoding will be used in that case. |
| * Set DIFF to TRUE if you expect the difference between consecutive numbers |
| * to be much smaller (~100 times) than the actual numbers. |
| */ |
| svn_packed__int_stream_t * |
| svn_packed__create_int_substream(svn_packed__int_stream_t *parent, |
| svn_boolean_t diff, |
| svn_boolean_t signed_ints); |
| |
| /* Create and return a new top-level byte sequence stream in ROOT. |
| */ |
| svn_packed__byte_stream_t * |
| svn_packed__create_bytes_stream(svn_packed__data_root_t *root); |
| |
| /* Write the unsigned integer VALUE to STEAM. |
| */ |
| void |
| svn_packed__add_uint(svn_packed__int_stream_t *stream, |
| apr_uint64_t value); |
| |
| /* Write the signed integer VALUE to STEAM. |
| */ |
| void |
| svn_packed__add_int(svn_packed__int_stream_t *stream, |
| apr_int64_t value); |
| |
| /* Write the sequence stating at DATA containing LEN bytes to STEAM. |
| */ |
| void |
| svn_packed__add_bytes(svn_packed__byte_stream_t *stream, |
| const char *data, |
| apr_size_t len); |
| |
| /* Write all contents of ROOT (including all sub-streams) to STREAM. |
| * Use SCRATCH_POOL for temporary allocations. |
| */ |
| svn_error_t * |
| svn_packed__data_write(svn_stream_t *stream, |
| svn_packed__data_root_t *root, |
| apr_pool_t *scratch_pool); |
| |
| |
| /* Reading data. */ |
| |
| /* Return the first integer stream in ROOT. Returns NULL in case there |
| * aren't any. |
| */ |
| svn_packed__int_stream_t * |
| svn_packed__first_int_stream(svn_packed__data_root_t *root); |
| |
| /* Return the first byte sequence stream in ROOT. Returns NULL in case |
| * there aren't any. |
| */ |
| svn_packed__byte_stream_t * |
| svn_packed__first_byte_stream(svn_packed__data_root_t *root); |
| |
| /* Return the next (sibling) integer stream to STREAM. Returns NULL in |
| * case there isn't any. |
| */ |
| svn_packed__int_stream_t * |
| svn_packed__next_int_stream(svn_packed__int_stream_t *stream); |
| |
| /* Return the next (sibling) byte sequence stream to STREAM. Returns NULL |
| * in case there isn't any. |
| */ |
| svn_packed__byte_stream_t * |
| svn_packed__next_byte_stream(svn_packed__byte_stream_t *stream); |
| |
| /* Return the first sub-stream of STREAM. Returns NULL in case there |
| * isn't any. |
| */ |
| svn_packed__int_stream_t * |
| svn_packed__first_int_substream(svn_packed__int_stream_t *stream); |
| |
| /* Return the number of integers left to read from STREAM. |
| */ |
| apr_size_t |
| svn_packed__int_count(svn_packed__int_stream_t *stream); |
| |
| /* Return the number of bytes left to read from STREAM. |
| */ |
| apr_size_t |
| svn_packed__byte_count(svn_packed__byte_stream_t *stream); |
| |
| /* Return the number of entries left to read from STREAM. |
| */ |
| apr_size_t |
| svn_packed__byte_block_count(svn_packed__byte_stream_t *stream); |
| |
| /* Return the next number from STREAM as unsigned integer. Returns 0 when |
| * reading beyond the end of the stream. |
| */ |
| apr_uint64_t |
| svn_packed__get_uint(svn_packed__int_stream_t *stream); |
| |
| /* Return the next number from STREAM as signed integer. Returns 0 when |
| * reading beyond the end of the stream. |
| */ |
| apr_int64_t |
| svn_packed__get_int(svn_packed__int_stream_t *stream); |
| |
| /* Return the next byte sequence from STREAM and set *LEN to the length |
| * of that sequence. Sets *LEN to 0 when reading beyond the end of the |
| * stream. |
| */ |
| const char * |
| svn_packed__get_bytes(svn_packed__byte_stream_t *stream, |
| apr_size_t *len); |
| |
| /* Allocate a new packed data root in RESULT_POOL, read its structure and |
| * stream contents from STREAM and return it in *ROOT_P. Use SCRATCH_POOL |
| * for temporary allocations. |
| */ |
| svn_error_t * |
| svn_packed__data_read(svn_packed__data_root_t **root_p, |
| svn_stream_t *stream, |
| apr_pool_t *result_pool, |
| apr_pool_t *scratch_pool); |
| |
| #ifdef __cplusplus |
| } |
| #endif /* __cplusplus */ |
| |
| #endif /* SVN_PACKED_DATA_H */ |