Pool.java
/*
* 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.
*/
package org.apache.tomcat.jni;
import java.nio.ByteBuffer;
/**
* Provides access to APR memory pools which are used to manage memory
* allocations for natively created instances.
*/
public class Pool {
/**
* Create a new pool.
*
* @param parent The parent pool. If this is 0, the new pool is a root pool.
* If it is non-zero, the new pool will inherit all of its
* parent pool's attributes, except the apr_pool_t will be a
* sub-pool.
*
* @return The pool we have just created.
*/
public static native long create(long parent);
/**
* Clear all memory in the pool and run all the cleanups. This also destroys all
* subpools.
* @param pool The pool to clear
* This does not actually free the memory, it just allows the pool
* to re-use this memory for the next allocation.
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native void clear(long pool);
/**
* Destroy the pool. This takes similar action as apr_pool_clear() and then
* frees all the memory. This will actually free the memory.
*
* @param pool The pool to destroy
*/
public static native void destroy(long pool);
/**
* Get the parent pool of the specified pool.
* @param pool The pool for retrieving the parent pool.
* @return The parent of the given pool.
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native long parentGet(long pool);
/**
* Determine if pool a is an ancestor of pool b
* @param a The pool to search
* @param b The pool to search for
* @return True if a is an ancestor of b, NULL is considered an ancestor
* of all pools.
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native boolean isAncestor(long a, long b);
/*
* Cleanup
*
* Cleanups are performed in the reverse order they were registered. That is:
* Last In, First Out. A cleanup function can safely allocate memory from
* the pool that is being cleaned up. It can also safely register additional
* cleanups which will be run LIFO, directly after the current cleanup
* terminates. Cleanups have to take caution in calling functions that
* create subpools. Subpools, created during cleanup will NOT automatically
* be cleaned up. In other words, cleanups are to clean up after themselves.
*/
/**
* Register a function to be called when a pool is cleared or destroyed
* @param pool The pool register the cleanup with
* @param o The object to call when the pool is cleared
* or destroyed
* @return The cleanup handler.
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native long cleanupRegister(long pool, Object o);
/**
* Remove a previously registered cleanup function
* @param pool The pool remove the cleanup from
* @param data The cleanup handler to remove from cleanup
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native void cleanupKill(long pool, long data);
/**
* Register a process to be killed when a pool dies.
* @param a The pool to use to define the processes lifetime
* @param proc The process to register
* @param how How to kill the process, one of:
* <PRE>
* APR_KILL_NEVER -- process is never sent any signals
* APR_KILL_ALWAYS -- process is sent SIGKILL on apr_pool_t cleanup
* APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
* APR_JUST_WAIT -- wait forever for the process to complete
* APR_KILL_ONLY_ONCE -- send SIGTERM and then wait
* </PRE>
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native void noteSubprocess(long a, long proc, int how);
/**
* Allocate a block of memory from a pool
* @param p The pool to allocate from
* @param size The amount of memory to allocate
* @return The ByteBuffer with allocated memory
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native ByteBuffer alloc(long p, int size);
/**
* Allocate a block of memory from a pool and set all of the memory to 0
* @param p The pool to allocate from
* @param size The amount of memory to allocate
* @return The ByteBuffer with allocated memory
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native ByteBuffer calloc(long p, int size);
/*
* User data management
*/
/**
* Set the data associated with the current pool
* @param data The user data associated with the pool.
* @param key The key to use for association
* @param pool The current pool
* <br><b>Warning :</b>
* The data to be attached to the pool should have a life span
* at least as long as the pool it is being attached to.
* Object attached to the pool will be globally referenced
* until the pool is cleared or dataSet is called with the null data.
* @return APR Status code.
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native int dataSet(long pool, String key, Object data);
/**
* Return the data associated with the current pool.
* @param key The key for the data to retrieve
* @param pool The current pool.
* @return the data
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native Object dataGet(long pool, String key);
/**
* Run all of the child_cleanups, so that any unnecessary files are
* closed because we are about to exec a new program
*
* @deprecated Unused. Will be removed in Tomcat 10.1
*/
@Deprecated
public static native void cleanupForExec();
}