Author: stefan2
Date: Sat Aug 3 01:09:28 2013
New Revision: 1509928
URL: http://svn.apache.org/r1509928
Log:
Add the usual header controls. No functional change.
* subversion/include/private/svn_packed_data.h
(): add #include blocker and extern "C" definition
Modified:
subversion/trunk/subversion/include/private/svn_packed_data.h
Modified: subversion/trunk/subversion/include/private/svn_packed_data.h
URL:
http://svn.apache.org/viewvc/subversion/trunk/subversion/include/private/svn_packed_data.h?rev=1509928&r1=1509927&r2=1509928&view=diff
==============================================================================
--- subversion/trunk/subversion/include/private/svn_packed_data.h (original)
+++ subversion/trunk/subversion/include/private/svn_packed_data.h Sat Aug 3
01:09:28 2013
@@ -1,242 +1,255 @@
-/* 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.
- * ====================================================================
- */
-
-#include "svn_string.h"
-#include "svn_io.h"
-
-/* 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 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);
+/* 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 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 */
