svn commit: r1147037 - /incubator/celix/site/trunk/content/celix/memorypools.mdtext

[ab...@apache.org]

Author: abroekhuis
Date: Fri Jul 15 08:56:50 2011
New Revision: 1147037

URL: http://svn.apache.org/viewvc?rev=1147037&view=rev
Log:
Added memory pools page

Added:
    incubator/celix/site/trunk/content/celix/memorypools.mdtext   (with props)

Added: incubator/celix/site/trunk/content/celix/memorypools.mdtext
URL: http://svn.apache.org/viewvc/incubator/celix/site/trunk/content/celix/memorypools.mdtext?rev=1147037&view=auto
==============================================================================
--- incubator/celix/site/trunk/content/celix/memorypools.mdtext (added)
+++ incubator/celix/site/trunk/content/celix/memorypools.mdtext Fri Jul 15 08:56:50 2011
@@ -0,0 +1,51 @@
+Title: Memory Pools
+Notice:    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.
+
+Celix uses the [Apache Portable Runtime][1] (APR) as abstraction layer for platforms. APR uses memory pools to make memory management easier. To be able to use memory pools the lifetime of "objects" must be known.
+
+This page details how Celix user APR memory pools and what the lifetime of objects within Celix is. This will result in some best practices that should be followed when using APR.
+
+Roughly, within Celix, the following object groups can be identified, where each object has its own memory pool:
+
+  - The framework 
+
+     The framework runs as long as the application and thus has the longest lifetime (if Celix is not embedded). The memory pool of the framework contains all objects belonging to the framework, for example the service registry etc.
+
+  - Installed bundles
+
+    For each bundle that is installed a new memory pool is created. This memory pool is active until the bundle is uninstalled. On this pool the metadata of the bundle is allocated, as well as other static aspects.
+The bundle pool is a child pool of the framework pool.
+
+  - Active bundles
+
+    If a bundle is started a new pool is created. This pool is used for all runtime aspects of the bundle, the bundle context, the loading of the library etc. A reference to this pool is also kept in the bundle context so that it can be used in the activator (and component). This pool is cleared and destroyed if the bundle is stopped.
+The active bundle pool is a child pool of the bundle pool.
+
+  - User invocation
+
+    During the lifetime of a bundle it is often needed to request information from the framework. If this invocation is only needed once, the pool from the bundle context can be used, but most likely invocations have to be repeated. To prevent a growing pool, for each invocation the caller has to supply a memory pool on which the request has to be allocated.
+It is up the caller to determine the life time of a request, and destroy the pool if it is no longer needed.
+To be sure all user pools are cleared, the active bundle pool should be used as parent. This guarantees all user pools will be destroyed if the bundle is stopped.
+
+The following diagram roughly depicts the state of a bundle and what pool must be/is used for that state.
+
+![alt text][2]
+
+
+  [1]: http://apr.apache.org
+  [2]: memory_pools.png
\ No newline at end of file

Propchange: incubator/celix/site/trunk/content/celix/memorypools.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native