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 * @file svn_temp_serializer.h
24 * @brief Helper API for serializing _temporarily_ data structures.
26 * @note This API is intended for efficient serialization and duplication
27 * of temporary, e.g. cached, data structures ONLY. It is not
28 * suitable for persistent data.
31 #ifndef SVN_TEMP_SERIALIZER_H
32 #define SVN_TEMP_SERIALIZER_H
34 #include "svn_string.h"
38 #endif /* __cplusplus */
40 /* forward declaration */
41 struct svn_stringbuf_t;
44 * The amount of extra memory allocated by #svn_temp_serializer__init for
45 * the internal buffer in addition to its suggested_buffer_size parameter.
46 * To allocate a 512 buffer, including overhead, just specify a size of
47 * 512 - SVN_TEMP_SERIALIZER__OVERHEAD.
49 #define SVN_TEMP_SERIALIZER__OVERHEAD (sizeof(svn_stringbuf_t) + 1)
52 * Opaque structure controlling the serialization process and holding the
53 * intermediate as well as final results.
55 typedef struct svn_temp_serializer__context_t svn_temp_serializer__context_t;
58 * Begin the serialization process for the @a source_struct and all objects
59 * referenced from it. @a struct_size must match the result of @c sizeof()
60 * of the actual structure. Due to the generic nature of the init function
61 * we can't determine the structure size as part of the function.
63 * It is possible to specify a @c NULL source_struct in which case the first
64 * call to svn_temp_serializer__push() will provide the root struct.
65 * Alternatively, one may even call svn_temp_serializer__add_string()
66 * but there is generally no point in doing so because the result will be
67 * simple string object in a #svn_stringbuf_t.
69 * You may suggest a larger initial buffer size in @a suggested_buffer_size
70 * to minimize the number of internal buffer re-allocations during the
71 * serialization process. All allocations will be made from @a pool.
73 * Pointers within the structure will be replaced by their serialized
74 * representation when the respective strings or sub-structures get
75 * serialized. This scheme allows only for tree-like, i.e. non-circular
78 * @return the serialization context.
80 svn_temp_serializer__context_t *
81 svn_temp_serializer__init(const void *source_struct,
82 apr_size_t struct_size,
83 apr_size_t suggested_buffer_size,
87 * Continue the serialization process of the @a source_struct that has
88 * already been serialized to @a buffer but contains references to new
89 * objects yet to serialize. I.e. this function allows you to append
90 * data to serialized structures returned by svn_temp_serializer__get().
92 * The current size of the serialized data is given in @a currently_used.
93 * If the allocated data buffer is actually larger, you may specifiy that
94 * size in @a currently_allocated to prevent unnecessary re-allocations.
95 * Otherwise, set it to 0.
97 * All allocations will be made from @a pool.
99 * Please note that only sub-structures of @a source_struct may be added.
100 * To add item referenced from other parts of the buffer, serialize from
101 * @a source_struct first, get the result from svn_temp_serializer__get()
102 * and call svn_temp_serializer__init_append for the next part.
104 * @return the serialization context.
106 svn_temp_serializer__context_t *
107 svn_temp_serializer__init_append(void *buffer,
109 apr_size_t currently_used,
110 apr_size_t currently_allocated,
114 * Begin serialization of a referenced sub-structure within the
115 * serialization @a context. @a source_struct must be a reference to the
116 * pointer in the original parent structure so that the correspondence in
117 * the serialized structure can be established. @a struct_size must match
118 * the result of @c sizeof() of the actual structure.
120 * Only in case that svn_temp_serializer__init() has not been provided
121 * with a root structure and this is the first call after the initialization,
122 * @a source_struct will point to a reference to the root structure instead
123 * of being related to some other.
125 * Sub-structures and strings will be added in a FIFO fashion. If you need
126 * add further sub-structures on the same level, you need to call
127 * svn_serializer__pop() to realign the serialization context.
130 svn_temp_serializer__push(svn_temp_serializer__context_t *context,
131 const void * const * source_struct,
132 apr_size_t struct_size);
135 * End the serialization of the current sub-structure. The serialization
136 * @a context will be focused back on the parent structure. You may then
137 * add further sub-structures starting from that level.
139 * It is not necessary to call this function just for symmetry at the end
140 * of the serialization process.
143 svn_temp_serializer__pop(svn_temp_serializer__context_t *context);
146 * Serialize a string referenced from the current structure within the
147 * serialization @a context. @a s must be a reference to the @c char*
148 * pointer in the original structure so that the correspondence in the
149 * serialized structure can be established.
151 * Only in case that svn_temp_serializer__init() has not been provided
152 * with a root structure and this is the first call after the initialization,
153 * @a s will not be related to some struct.
156 svn_temp_serializer__add_string(svn_temp_serializer__context_t *context,
157 const char * const * s);
160 * Set the serialized representation of the pointer @a ptr inside the
161 * current structure within the serialization @a context to @c NULL.
162 * This is particularly useful if the pointer is not @c NULL in the
166 svn_temp_serializer__set_null(svn_temp_serializer__context_t *context,
167 const void * const * ptr);
170 * @return the number of bytes currently used in the serialization buffer
171 * of the given serialization @a context.
174 svn_temp_serializer__get_length(svn_temp_serializer__context_t *context);
177 * @return a reference to the data buffer containing the data serialialized
178 * so far in the given serialization @a context.
180 struct svn_stringbuf_t *
181 svn_temp_serializer__get(svn_temp_serializer__context_t *context);
184 * Deserialization is straightforward: just copy the serialized buffer to
185 * a natively aligned memory location (APR pools will take care of that
186 * automatically) and resolve all pointers to sub-structures.
188 * To do the latter, call this function for each of these pointers, giving
189 * the start address of the copied buffer in @a buffer and a reference to
190 * the pointer to resolve in @a ptr.
193 svn_temp_deserializer__resolve(void *buffer, void **ptr);
196 * Similar to svn_temp_deserializer__resolve() but instead of modifying
197 * the buffer content, the resulting pointer is passed back to the caller
198 * as the return value.
201 svn_temp_deserializer__ptr(const void *buffer, const void *const *ptr);
205 #endif /* __cplusplus */
207 #endif /* SVN_TEMP_SERIALIZER_H */