// ************************************************************************
//    $Id: PhysicalMemoryManager.java 568 2005-07-12 00:33:41Z mdeters $
// ************************************************************************
//
//                                jRate
//
//               Copyright (C) 2001-2005 by Angelo Corsaro.
//                         <corsaro@cse.wustl.edu>
//                          All Rights Reserved.
//
//   Permission to use, copy, modify, and distribute this software and
//   its  documentation for any purpose is hereby  granted without fee,
//   provided that the above copyright notice appear in all copies and
//   that both that copyright notice and this permission notice appear
//   in  supporting  documentation. I don't make  any  representations
//   about the  suitability  of this  software for any  purpose. It is
//   provided "as is" without express or implied warranty.
//
//
// *************************************************************************
//
// *************************************************************************

package javax.realtime;

/**
 * This class provides a collection of methods to query, set up
 * filters for, and set up insertion/removal handlers for physical
 * memory ranges.
 *
 * @author <a href="mailto:mdeters@morgandeters.com">Morgan Deters</a>
 * @version 1.0
 * @since 0.3.8
 */
public final class PhysicalMemoryManager {
    /**
     * Specifies aligned memory.
     */
    public static String ALIGNED = "aligned";

    /**
     * Specifies that byte swapping should be used.
     */
    public static String BYTESWAP = "byteswap";

    /**
     * Specifies DMA memory.
     */
    public static String DMA = "dma";

    /**
     * Specifies shared memory.
     */
    public static String SHARED = "shared";

    /**
     * Construct a PhysicalMemoryManager.
     */
    PhysicalMemoryManager() {}

    /**
     * Register a memory type filter with the manager.  Both arguments
     * must be in immortal memory.
     *
     * @param name the type of memory handled by this filter
     * @param filter the filter
     * @throws DuplicateFilterException if a filter for this type of
     * memory is already registered
     * @throws RuntimeException too many filters have been registered
     * @throws IllegalArgumentException if the name parameter is
     * either an array of objects or if the name or the filter is in
     * immortal memory
     */
    public static void registerFilter(Object name,
                                            PhysicalMemoryTypeFilter filter)
        throws DuplicateFilterException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Dissociate the filter for the given memory type from the
     * manager.
     *
     * @param name the name associated with this filter
     */
    public static void removeFilter(Object name) {
        throw new UnimplementedFeatureError();
    }

    /**
     * Returns true if any part of the specified range of memory is
     * removable.
     *
     * @param address the base physical address of the queried range
     * @param size the extent of the queried range
     * @return true if <em>any part</em> of the range can be removed;
     * false otherwise
     */
    public static boolean isRemovable(long address, long size) {
        throw new UnimplementedFeatureError();
    }

    /**
     * Returns true if any part of the specified range of memory is
     * currently removed.
     *
     * @param address the base physical address of the queried range
     * @param size the extent of the queried range
     * @return true if <em>any part</em> of the rnage is currently
     * removed (or otherwise unavailable)
     */
    public static boolean isRemoved(long address, long size) {
        throw new UnimplementedFeatureError();
    }

    /**
     * Associate a handler with removal of memory in the given range.
     * If the size <em>or</em> base is negative, dissociate the given
     * handler from all onRemoval events.
     *
     * @param base the base physical address of the range
     * @param size the extent of the range
     * @param aeh the handler to associate/dissociate
     * @throws IllegalArgumentException if the range contains no
     * removable memory
     */
    public static void onRemoval(long base, long size, AsyncEventHandler aeh) {
        throw new UnimplementedFeatureError();
    }

    /**
     * Associate a handler with insertion of memory in the given
     * range.  If the size <em>or</em> base is negative, dissociate
     * the given handler from all onInsertion events.
     *
     * @param base the base physical address of the range
     * @param size the extent of the range
     * @param aeh the handler to associate/dissociate
     * @throws IllegalArgumentException if the range contains no
     * removable memory
     */
    public static void onInsertion(long base, long size,
                                   AsyncEventHandler aeh) {
        throw new UnimplementedFeatureError();
    }
}