Mailing-List: contact commits-help@apr.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@apr.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r813076 - in /apr/apr/branches/1.4.x: CHANGES
 include/apr_pools.h
Date: Wed, 09 Sep 2009 18:51:10 -0000
To: commits@apr.apache.org
From: minfrin@apache.org
Message-Id: <20090909185110.202382388868@eris.apache.org>

Author: minfrin
Date: Wed Sep  9 18:51:09 2009
New Revision: 813076

URL: http://svn.apache.org/viewvc?rev=813076&view=rev
Log:
Add comments describing the thread-safety properties of apr_pool_t.
Submitted by: Neil Conway nrc cs.berkeley.edu

Modified:
    apr/apr/branches/1.4.x/CHANGES
    apr/apr/branches/1.4.x/include/apr_pools.h

Modified: apr/apr/branches/1.4.x/CHANGES
URL: http://svn.apache.org/viewvc/apr/apr/branches/1.4.x/CHANGES?rev=813076&r1=813075&r2=813076&view=diff
==============================================================================
--- apr/apr/branches/1.4.x/CHANGES [utf-8] (original)
+++ apr/apr/branches/1.4.x/CHANGES [utf-8] Wed Sep  9 18:51:09 2009
@@ -1,13 +1,16 @@
                                                      -*- coding: utf-8 -*-
 Changes for APR 1.4.0
 
-  *) Make sure that "make check" is used in the RPM spec file, consistent
-     with apr-util. [Graham Leggett]
-
   *) SECURITY: CVE-2009-2412 (cve.mitre.org)
      Fix overflow in pools and rmm, where size alignment was taking place.
      [Matt Lewis <mattlewis@google.com>, Sander Striker]
 
+  *) Add comments describing the thread-safety properties of apr_pool_t.
+     [Neil Conway nrc cs.berkeley.edu]
+
+  *) Make sure that "make check" is used in the RPM spec file, consistent
+     with apr-util. [Graham Leggett]
+
   *) Pass default environment to testflock, testoc, testpipe, testsock,
      testshm and testproc children, so that tests run when APR is compiled
      with Intel C Compiler. [Bojan Smojver]

Modified: apr/apr/branches/1.4.x/include/apr_pools.h
URL: http://svn.apache.org/viewvc/apr/apr/branches/1.4.x/include/apr_pools.h?rev=813076&r1=813075&r2=813076&view=diff
==============================================================================
--- apr/apr/branches/1.4.x/include/apr_pools.h (original)
+++ apr/apr/branches/1.4.x/include/apr_pools.h Wed Sep  9 18:51:09 2009
@@ -28,10 +28,16 @@
  * particularly in the presence of die()).
  *
  * Instead, we maintain pools, and allocate items (both memory and I/O
- * handlers) from the pools --- currently there are two, one for per
- * transaction info, and one for config info.  When a transaction is over,
- * we can delete everything in the per-transaction apr_pool_t without fear,
- * and without thinking too hard about it either.
+ * handlers) from the pools --- currently there are two, one for
+ * per-transaction info, and one for config info.  When a transaction is
+ * over, we can delete everything in the per-transaction apr_pool_t without
+ * fear, and without thinking too hard about it either.
+ *
+ * Note that most operations on pools are not thread-safe: a single pool
+ * should only be accessed by a single thread at any given time. The one
+ * exception to this rule is creating a subpool of a given pool: one or more
+ * threads can safely create subpools at the same time that another thread
+ * accesses the parent pool.
  */
 
 #include "apr.h"
@@ -182,6 +188,10 @@
  * @param abort_fn A function to use if the pool cannot allocate more memory.
  * @param allocator The allocator to use with the new pool.  If NULL the
  *        allocator of the parent pool will be used.
+ * @remark This function is thread-safe, in the sense that multiple threads
+ *         can safely create subpools of the same parent pool concurrently.
+ *         Similarly, a subpool can be created by one thread at the same
+ *         time that another thread accesses the parent pool.
  */
 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
                                              apr_pool_t *parent,
@@ -287,6 +297,10 @@
  *        pool.  If it is non-NULL, the new pool will inherit all
  *        of its parent pool's attributes, except the apr_pool_t will
  *        be a sub-pool.
+ * @remark This function is thread-safe, in the sense that multiple threads
+ *         can safely create subpools of the same parent pool concurrently.
+ *         Similarly, a subpool can be created by one thread at the same
+ *         time that another thread accesses the parent pool.
  */
 #if defined(DOXYGEN)
 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
@@ -326,7 +340,7 @@
 #endif
 
 /**
- * Find the pools allocator
+ * Find the pool's allocator
  * @param pool The pool to get the allocator from.
  */
 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);