[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Pools in private/svn_cache.h

From: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Wed, 18 May 2011 12:13:46 +0200

I found the docstring of the deserializer function types unclear as to
the use of @a POOL...

So, the following patch attempts to clarify the role of pools in that
interface:

[[[
Index: subversion/include/private/svn_cache.h
===================================================================
--- subversion/include/private/svn_cache.h (revision 1124156)
+++ subversion/include/private/svn_cache.h (working copy)
@@ -50,16 +50,16 @@ extern "C" {
 
 /**
  * A function type for deserializing an object @a *out from the string
- * @a data of length @a data_len in the pool @a pool.
+ * @a data of length @a data_len into @a result_pool.
 */
 typedef svn_error_t *(*svn_cache__deserialize_func_t)(void **out,
                                                       const char *data,
                                                       apr_size_t data_len,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * A function type for deserializing an object @a *out from the string
- * @a data of length @a data_len in the pool @a pool. The extra information
+ * @a data of length @a data_len into @a result_pool. The extra information
  * @a baton passed into can be used to deserialize only a specific part or
  * sub-structure or to perform any other non-modifying operation that may
  * not require the whole structure to be processed.
@@ -68,7 +68,7 @@ typedef svn_error_t *(*svn_cache__partial_getter_f
                                                          const char *data,
                                                          apr_size_t data_len,
                                                          void *baton,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * A function type for modifying an already deserialized in the @a *data
@@ -76,30 +76,30 @@ typedef svn_error_t *(*svn_cache__partial_getter_f
  * to do will be provided in @a baton. The function may change the size of
  * data buffer and may re-allocate it if necessary. In that case, the new
  * values must be passed back in @a *data_len and @a *data, respectively.
- * Allocations will be done from @a pool.
+ * Allocations will be done from @a result_pool.
  */
 typedef svn_error_t *(*svn_cache__partial_setter_func_t)(char **data,
                                                          apr_size_t *data_len,
                                                          void *baton,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * A function type for serializing an object @a in into bytes. The
- * function should allocate the serialized value in @a pool, set
+ * function should allocate the serialized value in @a result_pool, set
  * @a *data to the serialized value, and set @a *data_len to its length.
  */
 typedef svn_error_t *(*svn_cache__serialize_func_t)(char **data,
                                                     apr_size_t *data_len,
                                                     void *in,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
- * A function type for transforming or ignoring errors. @a pool may
+ * A function type for transforming or ignoring errors. @a scratch_pool may
  * be used for temporary allocations.
  */
 typedef svn_error_t *(*svn_cache__error_handler_t)(svn_error_t *err,
                                                    void *baton,
- apr_pool_t *pool);
+ apr_pool_t *scratch_pool);
 
 /**
  * A wrapper around apr_memcache_t, provided essentially so that the
@@ -210,6 +210,7 @@ svn_cache__create_inprocess(svn_cache__t **cache_p
                             svn_boolean_t thread_safe,
                             const char *id,
                             apr_pool_t *pool);
+
 /**
  * Creates a new cache in @a *cache_p, communicating to a memcached
  * process via @a memcache. The elements in the cache will be indexed
@@ -218,7 +219,7 @@ svn_cache__create_inprocess(svn_cache__t **cache_p
  * serialize_func and deserialized using @a deserialize_func. Because
  * the same memcached server may cache many different kinds of values,
  * @a prefix should be specified to differentiate this cache from
- * other caches. @a *cache_p will be allocated in @a pool.
+ * other caches. @a *cache_p will be allocated in @a result_pool.
  *
  * If @a deserialize_func is NULL, then the data is returned as an
  * svn_string_t; if @a serialize_func is NULL, then the data is
@@ -238,11 +239,11 @@ svn_cache__create_memcache(svn_cache__t **cache_p,
                            svn_cache__deserialize_func_t deserialize_func,
                            apr_ssize_t klen,
                            const char *prefix,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * Given @a config, returns an APR memcached interface in @a
- * *memcache_p allocated in @a pool if @a config contains entries in
+ * *memcache_p allocated in @a result_pool if @a config contains entries in
  * the SVN_CACHE_CONFIG_CATEGORY_MEMCACHED_SERVERS section describing
  * memcached servers; otherwise, sets @a *memcache_p to NULL.
  *
@@ -253,7 +254,7 @@ svn_cache__create_memcache(svn_cache__t **cache_p,
 svn_error_t *
 svn_cache__make_memcache_from_config(svn_memcache_t **memcache_p,
                                      svn_config_t *config,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * Creates a new membuffer cache object in @a *cache. It will contain
@@ -269,14 +270,14 @@ svn_cache__make_memcache_from_config(svn_memcache_
  * If access to the resulting cache object is guranteed to be serialized,
  * @a thread_safe may be set to @a FALSE for maximum performance.
  *
- * Allocations will be made in @a pool, in particular the data buffers.
+ * Allocations will be made in @a result_pool, in particular the data buffers.
  */
 svn_error_t *
 svn_cache__membuffer_cache_create(svn_membuffer_t **cache,
                                   apr_size_t total_size,
                                   apr_size_t directory_size,
                                   svn_boolean_t thread_safe,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * Creates a new cache in @a *cache_p, storing the data in a potentially
@@ -286,7 +287,7 @@ svn_cache__membuffer_cache_create(svn_membuffer_t
  * serialize_func and deserialized using @a deserialize_func. Because
  * the same memcache object may cache many different kinds of values
  * form multiple caches, @a prefix should be specified to differentiate
- * this cache from other caches. @a *cache_p will be allocated in @a pool.
+ * this cache from other caches. @a *cache_p will be allocated in @a result_pool.
  *
  * If @a deserialize_func is NULL, then the data is returned as an
  * svn_string_t; if @a serialize_func is NULL, then the data is
@@ -304,7 +305,7 @@ svn_cache__create_membuffer_cache(svn_cache__t **c
                                   svn_cache__deserialize_func_t deserialize,
                                   apr_ssize_t klen,
                                   const char *prefix,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * Sets @a handler to be @a cache's error handling routine. If any
@@ -312,14 +313,14 @@ svn_cache__create_membuffer_cache(svn_cache__t **c
  * handler will be called with @a baton and the error, and the
  * original function will return whatever error @a handler returns
  * instead (possibly SVN_NO_ERROR); @a handler will receive the pool
- * passed to the svn_cache__* function. @a pool is used for temporary
+ * passed to the svn_cache_* function. @a scratch_pool is used for temporary
  * allocations.
  */
 svn_error_t *
 svn_cache__set_error_handler(svn_cache__t *cache,
                              svn_cache__error_handler_t handler,
                              void *baton,
- apr_pool_t *pool);
+ apr_pool_t *scratch_pool);
 
 /**
  * Returns @c TRUE if the @a cache supports objects of the given @a size.
]]]

[[[
Index: subversion/include/private/svn_cache.h
===================================================================
--- subversion/include/private/svn_cache.h (revision 1124156)
+++ subversion/include/private/svn_cache.h (working copy)
@@ -337,19 +338,20 @@ svn_cache__is_cachable(svn_cache__t *cache,
 /**
  * Fetches a value indexed by @a key from @a cache into @a *value,
  * setting @a *found to TRUE iff it is in the cache and FALSE if it is
- * not found. The value is copied into @a pool using the copy
+ * not found. The value is copied into @a result_pool using the copy
  * function provided to the cache's constructor.
+ * ### what copy function? there are serialize/deserialize functions, no copy functions
  */
 svn_error_t *
 svn_cache__get(void **value,
                svn_boolean_t *found,
                svn_cache__t *cache,
                const void *key,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
- * Stores the value @a value under the key @a key in @a cache. @a pool
- * is used only for temporary allocations. The cache makes copies of
+ * Stores the value @a value under the key @a key in @a cache. Uses @a
+ * scratch_pool for temporary allocations. The cache makes copies of
  * @a key and @a value if necessary (that is, @a key and @a value may
  * have shorter lifetimes than the cache).
  *
@@ -363,12 +365,12 @@ svn_error_t *
 svn_cache__set(svn_cache__t *cache,
                const void *key,
                void *value,
- apr_pool_t *pool);
+ apr_pool_t *scratch_pool);
 
 /**
  * Iterates over the elements currently in @a cache, calling @a func
  * for each one until there are no more elements or @a func returns an
- * error. Uses @a pool for temporary allocations.
+ * error. Uses @a scratch_pool for temporary allocations.
  *
  * If @a completed is not NULL, then on return - if @a func returns no
  * errors - @a *completed will be set to @c TRUE.
@@ -390,7 +392,7 @@ svn_cache__iter(svn_boolean_t *completed,
                 svn_cache__t *cache,
                 svn_iter_apr_hash_cb_t func,
                 void *baton,
- apr_pool_t *pool);
+ apr_pool_t *scratch_pool);
 
 /**
  * Similar to @ref svn_cache__set but will call a specific de-serialization
@@ -425,21 +427,21 @@ svn_cache__set_partial(svn_cache__t *cache,
  * Collect all available usage statistics on the cache instance @a cache
  * and write the data into @a info. If @a reset has been set, access
  * counters will be reset right after copying the statistics info.
- * @a pool will be used for allocations.
+ * @a result_pool will be used for allocations.
  */
 svn_error_t *
 svn_cache__get_info(svn_cache__t *cache,
                     svn_cache__info_t *info,
                     svn_boolean_t reset,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /**
  * Return the information given in @a info formatted as a multi-line string.
- * Allocations take place in @a pool.
+ * Allocations take place in @a result_pool.
  */
 svn_string_t *
 svn_cache__format_info(const svn_cache__info_t *info,
- apr_pool_t *pool);
+ apr_pool_t *result_pool);
 
 /* Access the process-global (singleton) membuffer cache. The first call
  * will automatically allocate the cache using the current cache config.
]]]

Also, should (some of) these functions convert to the dual-pool
paradigm?
Received on 2011-05-18 12:14:25 CEST

This is an archived mail posted to the Subversion Dev mailing list.