// ************************************************************************
//    $Id: VTPhysicalMemory.java 566 2005-07-11 22:24:13Z 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;

/**
 * A scoped memory area with a variable-time allocator that provides
 * storage from a particular type of memory.
 *
 * @author <a href="mailto:mdeters@morgandeters.com">Morgan Deters</a>
 * @version 1.0
 * @since 0.3.8
 */
public class VTPhysicalMemory extends ScopedMemory {
    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param size the requested size of the memory area
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException never thrown (but the spec
     * requires it in the signature)
     */
    public VTPhysicalMemory(Object type, long size)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException {
        this(type, size, (Runnable)null);
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param base the requested base physical address of the memory
     * area
     * @param size the requested size of the memory area
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException if the memory type and
     * offset are in conflict
     * @throws MemoryInUseException at least some of the requested
     * memory range is already in use
     */
    public VTPhysicalMemory(Object type, long base, long size)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException,
               MemoryInUseException {
        this(type, base, size, null);
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param base the requested base physical address of the memory
     * area
     * @param size the requested size of the memory area
     * @param logic the <code>run()</code> method invoked when {@link
     * MemoryArea#enter()} is called
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException if the memory type and
     * offset are in conflict
     * @throws MemoryInUseException at least some of the requested
     * memory range is already in use
     */
    public VTPhysicalMemory(Object type, long base, long size,
                            Runnable logic)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException,
               MemoryInUseException {
        super(size, logic);
        RealtimeSystem.getSecurityManager().
            checkAccessPhysicalRange(base, base + size);
        throw new UnimplementedFeatureError();
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param size the requested size of the memory area
     * @param logic the <code>run()</code> method invoked when {@link
     * MemoryArea#enter()} is called
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException never thrown (but the spec
     * requires it in the signature)
     */
    public VTPhysicalMemory(Object type, long size, Runnable logic)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException {
        super(size, logic);
        // When this is implemented, make sure to check permission for
        // the range of physical addresses that end up being used.
        RealtimeSystem.getSecurityManager().checkAccessPhysical();
        throw new UnimplementedFeatureError();
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param base the requested base physical address of the memory
     * area
     * @param size the requested size of the memory area
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException if the memory type and
     * offset are in conflict
     * @throws MemoryInUseException at least some of the requested
     * memory range is already in use
     */
    public VTPhysicalMemory(Object type, long base, SizeEstimator size)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException,
               MemoryInUseException {
        this(type, base, size.getEstimate());
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param base the requested base physical address of the memory
     * area
     * @param size the requested size of the memory area
     * @param logic the <code>run()</code> method invoked when {@link
     * MemoryArea#enter()} is called
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException if the memory type and
     * offset are in conflict
     * @throws MemoryInUseException at least some of the requested
     * memory range is already in use
     */
    public VTPhysicalMemory(Object type, long base, SizeEstimator size,
                            Runnable logic)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException,
               MemoryInUseException {
        this(type, base, size.getEstimate(), logic);
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param size the requested size of the memory area
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException never thrown (but the spec
     * requires it in the signature)
     */
    public VTPhysicalMemory(Object type, SizeEstimator size)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException {
        this(type, size.getEstimate());
    }

    /**
     * Construct an {@link VTPhysicalMemory}.
     *
     * @param type the requested type of memory
     * @param size the requested size of the memory area
     * @param logic the <code>run()</code> method invoked when {@link
     * MemoryArea#enter()} is called
     * @throws SecurityException if the calling execution context
     * doesn't have permission to access this memory area
     * @throws SizeOutOfBoundsException the size is negative or
     * extends into an invalid range of memory
     * @throws UnsupportedPhysicalMemoryException hardware doesn't
     * support the type of memory requested
     * @throws MemoryTypeConflictException never thrown (but the spec
     * requires it in the signature)
     */
    public VTPhysicalMemory(Object type, SizeEstimator size,
                            Runnable logic)
        throws SecurityException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException {
        this(type, size.getEstimate(), logic);
    }

    /**
     * Returns a user-friendly {@link String} describing this {@link
     * VTPhysicalMemory}.
     *
     * @return a user-friendly {@link String} describing this {@link
     * VTPhysicalMemory}.
     */
    public String toString() {
        return "VTPhysicalMemory";
    }
}