Pool


1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one or more
3    *  contributor license agreements.  See the NOTICE file distributed with
4    *  this work for additional information regarding copyright ownership.
5    *  The ASF licenses this file to You under the Apache License, Version 2.0
6    *  (the "License"); you may not use this file except in compliance with
7    *  the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   *  Unless required by applicable law or agreed to in writing, software
12   *  distributed under the License is distributed on an "AS IS" BASIS,
13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   *  See the License for the specific language governing permissions and
15   *  limitations under the License.
16   */
17  
18  package org.apache.tomcat.jni;
19  
20  import java.nio.ByteBuffer  ;
21  
22  /** Pool
23   *
24   * @author Mladen Turk
25   * @version $Revision: 467222 $, $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
26   */
27  
28  public class Pool {
29  
30      /**
31       * Create a new pool.
32       * @param parent The parent pool.  If this is 0, the new pool is a root
33       * pool.  If it is non-zero, the new pool will inherit all
34       * of its parent pool's attributes, except the apr_pool_t will
35       * be a sub-pool.
36       * @return The pool we have just created.
37      */
38      public static native long create(long parent);
39  
40      /**
41       * Clear all memory in the pool and run all the cleanups. This also destroys all
42       * subpools.
43       * @param pool The pool to clear
44       * This does not actually free the memory, it just allows the pool
45       *         to re-use this memory for the next allocation.
46       */
47      public static native void clear(long pool);
48  
49      /**
50       * Destroy the pool. This takes similar action as apr_pool_clear() and then
51       * frees all the memory.
52       * This will actually free the memory
53       * @param pool The pool to destroy
54       */
55      public static native void destroy(long pool);
56  
57      /**
58       * Get the parent pool of the specified pool.
59       * @param pool The pool for retrieving the parent pool.
60       * @return The parent of the given pool.
61       */
62      public static native long parentGet(long pool);
63  
64      /**
65       * Determine if pool a is an ancestor of pool b
66       * @param a The pool to search
67       * @param b The pool to search for
68       * @return True if a is an ancestor of b, NULL is considered an ancestor
69       * of all pools.
70       */
71      public static native boolean isAncestor(long a, long b);
72  
73  
74      /*
75       * Cleanup
76       *
77       * Cleanups are performed in the reverse order they were registered.  That is:
78       * Last In, First Out.  A cleanup function can safely allocate memory from
79       * the pool that is being cleaned up. It can also safely register additional
80       * cleanups which will be run LIFO, directly after the current cleanup
81       * terminates.  Cleanups have to take caution in calling functions that
82       * create subpools. Subpools, created during cleanup will NOT automatically
83       * be cleaned up.  In other words, cleanups are to clean up after themselves.
84       */
85  
86      /**
87       * Register a function to be called when a pool is cleared or destroyed
88       * @param pool The pool register the cleanup with
89       * @param o The object to call when the pool is cleared
90       *                      or destroyed
91       * @return The cleanup handler.
92       */
93      public static native long cleanupRegister(long pool, Object   o);
94  
95      /**
96       * Remove a previously registered cleanup function
97       * @param pool The pool remove the cleanup from
98       * @param data The cleanup handler to remove from cleanup
99       */
100     public static native void cleanupKill(long pool, long data);
101 
102     /**
103      * Register a process to be killed when a pool dies.
104      * @param a The pool to use to define the processes lifetime
105      * @param proc The process to register
106      * @param how How to kill the process, one of:
107      * <PRE>
108      * APR_KILL_NEVER         -- process is never sent any signals
109      * APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
110      * APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
111      * APR_JUST_WAIT          -- wait forever for the process to complete
112      * APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
113      * </PRE>
114      */
115     public static native void noteSubprocess(long a, long proc, int how);
116 
117     /**
118      * Allocate a block of memory from a pool
119      * @param p The pool to allocate from
120      * @param size The amount of memory to allocate
121      * @return The ByteBuffer with allocated memory
122      */
123     public static native ByteBuffer   alloc(long p, int size);
124 
125     /**
126      * Allocate a block of memory from a pool and set all of the memory to 0
127      * @param p The pool to allocate from
128      * @param size The amount of memory to allocate
129      * @return The ByteBuffer with allocated memory
130      */
131     public static native ByteBuffer   calloc(long p, int size);
132 
133     /*
134      * User data management
135      */
136 
137     /**
138      * Set the data associated with the current pool
139      * @param data The user data associated with the pool.
140      * @param key The key to use for association
141      * @param pool The current pool
142      * <br /><b>Warning :</b>
143      * The data to be attached to the pool should have a life span
144      * at least as long as the pool it is being attached to.
145      * Object attached to the pool will be globaly referenced
146      * untill the pool is cleared or dataSet is called with the null data.
147      * @return APR Status code.
148      */
149      public static native int dataSet(long pool, String   key, Object   data);
150 
151     /**
152      * Return the data associated with the current pool.
153      * @param key The key for the data to retrieve
154      * @param pool The current pool.
155      */
156      public static native Object   dataGet(long pool, String   key);
157 
158     /**
159      * Run all of the child_cleanups, so that any unnecessary files are
160      * closed because we are about to exec a new program
161      */
162     public static native void cleanupForExec();
163 
164 }
165
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags