001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.tomcat.jni;
019:
020: import java.nio.ByteBuffer;
021:
022: /** Pool
023: *
024: * @author Mladen Turk
025: * @version $Revision: 467222 $, $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
026: */
027:
028: public class Pool {
029:
030: /**
031: * Create a new pool.
032: * @param parent The parent pool. If this is 0, the new pool is a root
033: * pool. If it is non-zero, the new pool will inherit all
034: * of its parent pool's attributes, except the apr_pool_t will
035: * be a sub-pool.
036: * @return The pool we have just created.
037: */
038: public static native long create(long parent);
039:
040: /**
041: * Clear all memory in the pool and run all the cleanups. This also destroys all
042: * subpools.
043: * @param pool The pool to clear
044: * This does not actually free the memory, it just allows the pool
045: * to re-use this memory for the next allocation.
046: */
047: public static native void clear(long pool);
048:
049: /**
050: * Destroy the pool. This takes similar action as apr_pool_clear() and then
051: * frees all the memory.
052: * This will actually free the memory
053: * @param pool The pool to destroy
054: */
055: public static native void destroy(long pool);
056:
057: /**
058: * Get the parent pool of the specified pool.
059: * @param pool The pool for retrieving the parent pool.
060: * @return The parent of the given pool.
061: */
062: public static native long parentGet(long pool);
063:
064: /**
065: * Determine if pool a is an ancestor of pool b
066: * @param a The pool to search
067: * @param b The pool to search for
068: * @return True if a is an ancestor of b, NULL is considered an ancestor
069: * of all pools.
070: */
071: public static native boolean isAncestor(long a, long b);
072:
073: /*
074: * Cleanup
075: *
076: * Cleanups are performed in the reverse order they were registered. That is:
077: * Last In, First Out. A cleanup function can safely allocate memory from
078: * the pool that is being cleaned up. It can also safely register additional
079: * cleanups which will be run LIFO, directly after the current cleanup
080: * terminates. Cleanups have to take caution in calling functions that
081: * create subpools. Subpools, created during cleanup will NOT automatically
082: * be cleaned up. In other words, cleanups are to clean up after themselves.
083: */
084:
085: /**
086: * Register a function to be called when a pool is cleared or destroyed
087: * @param pool The pool register the cleanup with
088: * @param o The object to call when the pool is cleared
089: * or destroyed
090: * @return The cleanup handler.
091: */
092: public static native long cleanupRegister(long pool, Object o);
093:
094: /**
095: * Remove a previously registered cleanup function
096: * @param pool The pool remove the cleanup from
097: * @param data The cleanup handler to remove from cleanup
098: */
099: public static native void cleanupKill(long pool, long data);
100:
101: /**
102: * Register a process to be killed when a pool dies.
103: * @param a The pool to use to define the processes lifetime
104: * @param proc The process to register
105: * @param how How to kill the process, one of:
106: * <PRE>
107: * APR_KILL_NEVER -- process is never sent any signals
108: * APR_KILL_ALWAYS -- process is sent SIGKILL on apr_pool_t cleanup
109: * APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
110: * APR_JUST_WAIT -- wait forever for the process to complete
111: * APR_KILL_ONLY_ONCE -- send SIGTERM and then wait
112: * </PRE>
113: */
114: public static native void noteSubprocess(long a, long proc, int how);
115:
116: /**
117: * Allocate a block of memory from a pool
118: * @param p The pool to allocate from
119: * @param size The amount of memory to allocate
120: * @return The ByteBuffer with allocated memory
121: */
122: public static native ByteBuffer alloc(long p, int size);
123:
124: /**
125: * Allocate a block of memory from a pool and set all of the memory to 0
126: * @param p The pool to allocate from
127: * @param size The amount of memory to allocate
128: * @return The ByteBuffer with allocated memory
129: */
130: public static native ByteBuffer calloc(long p, int size);
131:
132: /*
133: * User data management
134: */
135:
136: /**
137: * Set the data associated with the current pool
138: * @param data The user data associated with the pool.
139: * @param key The key to use for association
140: * @param pool The current pool
141: * <br /><b>Warning :</b>
142: * The data to be attached to the pool should have a life span
143: * at least as long as the pool it is being attached to.
144: * Object attached to the pool will be globaly referenced
145: * untill the pool is cleared or dataSet is called with the null data.
146: * @return APR Status code.
147: */
148: public static native int dataSet(long pool, String key, Object data);
149:
150: /**
151: * Return the data associated with the current pool.
152: * @param key The key for the data to retrieve
153: * @param pool The current pool.
154: */
155: public static native Object dataGet(long pool, String key);
156:
157: /**
158: * Run all of the child_cleanups, so that any unnecessary files are
159: * closed because we are about to exec a new program
160: */
161: public static native void cleanupForExec();
162:
163: }
|