/*
 *  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;

Pool
Author:
Mladen Turk/** Pool
 *
 * @author Mladen Turk
 */
public class Pool {

    
Create a new pool.
Params:
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.
Returns:
The pool we have just created./**
     * 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.
Params:
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./**
     * 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.
     */
    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
Params:
pool – The pool to destroy/**
     * 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.
Params:
pool – The pool for retrieving the parent pool.
Returns:
The parent of the given 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.
     */
    public static native long parentGet(long pool);

    
Determine if pool a is an ancestor of pool b
Params:
a – The pool to search
b – The pool to search for
Returns:
True if a is an ancestor of b, NULL is considered an ancestor
of all pools./**
     * 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.
     */
    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
Params:
pool – The pool register the cleanup with
o – The object to call when the pool is cleared
                     or destroyed
Returns:
The cleanup handler./**
     * 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.
     */
    public static native long cleanupRegister(long pool, Object o);

    
Remove a previously registered cleanup function
Params:
pool – The pool remove the cleanup from
data – The cleanup handler to remove from cleanup/**
     * Remove a previously registered cleanup function
     * @param pool The pool remove the cleanup from
     * @param data The cleanup handler to remove from cleanup
     */
    public static native void cleanupKill(long pool, long data);

    
Register a process to be killed when a pool dies.
Params:
a – The pool to use to define the processes lifetime
proc – The process to register
how – How to kill the process, one of:
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
/**
     * 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>
     */
    public static native void noteSubprocess(long a, long proc, int how);

    
Allocate a block of memory from a pool
Params:
p – The pool to allocate from
size – The amount of memory to allocate
Returns:
The ByteBuffer with allocated memory/**
     * 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
     */
    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
Params:
p – The pool to allocate from
size – The amount of memory to allocate
Returns:
The ByteBuffer with allocated memory/**
     * 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
     */
    public static native ByteBuffer calloc(long p, int size);

    /*
     * User data management
     */

    
Set the data associated with the current pool
Params:
data – The user data associated with the pool.
key – The key to use for association
pool – The current pool

Warning :
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.
Returns:
APR Status code./**
     * 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.
     */
     public static native int dataSet(long pool, String key, Object data);

    
Return the data associated with the current pool.
Params:
key – The key for the data to retrieve
pool – The current pool.
Returns:
the 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
     */
     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
/**
     * Run all of the child_cleanups, so that any unnecessary files are
     * closed because we are about to exec a new program
     */
    public static native void cleanupForExec();

}