subversion-1.9.7HEADsubversion-1.9.7master

1 files changed, 154 insertions, 0 deletions

diff --git a/subversion/include/private/svn_object_pool.h b/subversion/include/private/svn_object_pool.h
new file mode 100644
index 0000000..7a9383e
--- /dev/null
+++ b/subversion/include/private/svn_object_pool.h
@@ -0,0 +1,154 @@
+/**
+ * @copyright
+ * ====================================================================
+ *    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.
+ * ====================================================================
+ * @endcopyright
+ *
+ * @file svn_object_pool.h
+ * @brief multithreaded object pool API
+ *
+ * This is the core data structure behind various object pools.  It
+ * provides a thread-safe associative container for object instances of
+ * the same type.
+ *
+ * Memory and lifetime management for the objects are handled by the pool.
+ * Reference counting takes care that neither objects nor the object pool
+ * get actually destroyed while other parts depend on them.  All objects
+ * are thought to be recycle-able and live in their own root memory pools
+ * making them (potentially) safe to be used from different threads.
+ * Currently unused objects may be kept around for a while and returned
+ * by the next lookup.
+ *
+ * Two modes are supported: shared use and exclusive use.  In shared mode,
+ * any object can be handed out to multiple users and in potentially
+ * different threads at the same time.  In exclusive mode, the same object
+ * will only be referenced at most once.
+ *
+ * Object creation and access must be provided outside this structure.
+ * In particular, the using container will usually wrap the actual object
+ * in a meta-data struct containing key information etc and must provide
+ * getters and setters for those wrapper structs.
+ */
+
+
+
+#ifndef SVN_OBJECT_POOL_H
+#define SVN_OBJECT_POOL_H
+
+#include <apr.h>        /* for apr_int64_t */
+#include <apr_pools.h>  /* for apr_pool_t */
+#include <apr_hash.h>   /* for apr_hash_t */
+
+#include "svn_types.h"
+
+#include "private/svn_mutex.h"
+#include "private/svn_string_private.h"
+
+
+
+/* The opaque object container type. */
+typedef struct svn_object_pool__t svn_object_pool__t;
+
+/* Extract the actual object from the WRAPPER using optional information
+ * from BATON (provided through #svn_object_pool__lookup) and return it.
+ * The result will be used with POOL and must remain valid throughout
+ * POOL's lifetime.
+ *
+ * It is legal to return a copy, allocated in POOL, of the wrapped object.
+ */
+typedef void * (* svn_object_pool__getter_t)(void *wrapper,
+                                             void *baton,
+                                             apr_pool_t *pool);
+
+/* Copy the information from the SOURCE object wrapper into the already
+ * existing *TARGET object wrapper using POOL for allocations and BATON
+ * for optional context (provided through #svn_object_pool__insert).
+ */
+typedef svn_error_t * (* svn_object_pool__setter_t)(void **target,
+                                                    void *source,
+                                                    void *baton,
+                                                    apr_pool_t *pool);
+
+/* Create a new object pool in POOL and return it in *OBJECT_POOL.
+ * Objects will be extracted using GETTER and updated using SETTER.  Either
+ * one (or both) may be NULL and the default implementation assumes that
+ * wrapper == object and updating is a no-op.
+ *
+ * If THREAD_SAFE is not set, neither the object pool nor the object
+ * references returned from it may be accessed from multiple threads.
+ *
+ * It is not legal to call any API on the object pool after POOL got
+ * cleared or destroyed.  However, existing object references handed out
+ * from the object pool remain valid and will keep the internal pool data
+ * structures alive for as long as such object references exist.
+ */
+svn_error_t *
+svn_object_pool__create(svn_object_pool__t **object_pool,
+                        svn_object_pool__getter_t getter,
+                        svn_object_pool__setter_t setter,
+                        svn_boolean_t thread_safe,
+                        apr_pool_t *pool);
+
+/* Return the root pool containing the OBJECT_POOL and all sub-structures.
+ */
+apr_pool_t *
+svn_object_pool__new_wrapper_pool(svn_object_pool__t *object_pool);
+
+/* Return the mutex used to serialize all OBJECT_POOL access.
+ */
+svn_mutex__t *
+svn_object_pool__mutex(svn_object_pool__t *object_pool);
+
+/* Return the number of object instances (used or unused) in OBJECT_POOL.
+ */
+unsigned
+svn_object_pool__count(svn_object_pool__t *object_pool);
+
+/* In OBJECT_POOL, look for an available object by KEY and return a
+ * reference to it in *OBJECT.  If none can be found, *OBJECT will be NULL.
+ * BATON will be passed to OBJECT_POOL's getter function.  The reference
+ * will be returned when *RESULT_POOL gets cleaned up or destroyed.
+ */
+svn_error_t *
+svn_object_pool__lookup(void **object,
+                        svn_object_pool__t *object_pool,
+                        svn_membuf_t *key,
+                        void *baton,
+                        apr_pool_t *result_pool);
+
+/* Store the wrapped object WRAPPER under KEY in OBJECT_POOL and return
+ * a reference to the object in *OBJECT (just like lookup).
+ *
+ * The object must have been created in WRAPPER_POOL and the latter must
+ * be a sub-pool of OBJECT_POOL's root POOL (see #svn_object_pool__pool).
+ *
+ * BATON will be passed to OBJECT_POOL's setter and getter functions.
+ * The reference will be returned when *RESULT_POOL gets cleaned up or
+ * destroyed.
+ */
+svn_error_t *
+svn_object_pool__insert(void **object,
+                        svn_object_pool__t *object_pool,
+                        const svn_membuf_t *key,
+                        void *wrapper,
+                        void *baton,
+                        apr_pool_t *wrapper_pool,
+                        apr_pool_t *result_pool);
+
+#endif /* SVN_OBJECT_POOL_H */