/*
* This file is part of the Jikes RVM project (http://jikesrvm.org).
*
* This file is licensed to You under the Eclipse Public License (EPL);
* You may not use this file except in compliance with the License. You
* may obtain a copy of the License at
*
* http://www.opensource.org/licenses/eclipse-1.0.php
*
* See the COPYRIGHT.txt file distributed with this work for information
* regarding copyright ownership.
*/
package org.mmtk.utility.heap;
import org.mmtk.plan.Plan;
import org.mmtk.policy.Space;
import org.mmtk.utility.Constants;
import org.mmtk.utility.options.ProtectOnRelease;
import org.mmtk.utility.options.Options;
import org.mmtk.vm.Lock;
import org.mmtk.vm.VM;
import org.vmmagic.pragma.*;
import org.vmmagic.unboxed.*;
/**
* This class manages the allocation of pages for a space. When a
* page is requested by the space both a page budget and the use of
* virtual address space are checked. If the request for space can't
* be satisfied (for either reason) a GC may be triggered.<p>
*
* This class is abstract, and is subclassed with monotone and
* freelist variants, which reflect monotonic and ad hoc space usage
* respectively. Monotonic use is easier to manage, but is obviously
* more restrictive (useful for copying collectors which allocate
* monotonically before freeing the entire space and starting over).
*/
@Uninterruptible
public abstract class PageResource implements Constants {
/****************************************************************************
*
* Class variables
*/
protected static final boolean ZERO_ON_RELEASE = false; // debugging
private static final Lock classLock;
private static long cumulativeCommitted = 0;
/****************************************************************************
*
* Instance variables
*/
// page budgeting
protected int reserved;
protected int committed;
protected int required;
private final int pageBudget;
protected final boolean contiguous;
protected final Space space;
protected Address start; // only for contiguous
// locking
private final Lock gcLock; // used during GC
private final Lock mutatorLock; // used by mutators
/****************************************************************************
*
* Initialization
*/
static {
classLock = VM.newLock("PageResource");
Options.protectOnRelease = new ProtectOnRelease();
}
/**
* Constructor
*
* @param pageBudget The budget of pages available to this memory
* manager before it must poll the collector.
* @param space The space to which this resource is attached
*/
private PageResource(int pageBudget, Space space, boolean contiguous) {
this.pageBudget = pageBudget;
this.contiguous = contiguous;
this.space = space;
gcLock = VM.newLock(space.getName() + ".gcLock");
mutatorLock = VM.newLock(space.getName() + ".mutatorLock");
}
/**
* Constructor for discontiguous spaces
*
* @param pageBudget The budget of pages available to this memory
* manager before it must poll the collector.
* @param space The space to which this resource is attached
*/
PageResource(int pageBudget, Space space) {
this(pageBudget, space, false);
}
/**
* Constructor for contiguous spaces
*
* @param pageBudget The budget of pages available to this memory
* manager before it must poll the collector.
* @param space The space to which this resource is attached
*/
PageResource(int pageBudget, Space space, Address start) {
this(pageBudget, space, true);
this.start = start;
}
/**
* Return the number of available physical pages for this resource.
*
* Note: This just considers physical pages (ie virtual memory pages
* allocated for use by this resource). This calculation is orthogonal
* to and does not consider any restrictions on the number of pages
* this resource may actually use at any time (ie the number of
* committed and reserved pages).<p>
*
* Note: The calculation is made on the assumption that all space that
* could be assigned to this resource would be assigned to this resource
* (ie the unused discontiguous space could just as likely be assigned
* to another competing resource).
*
* @return The number of available physical pages for this resource.
*/
public abstract int getAvailablePhysicalPages();
/**
* Reserve pages.<p>
*
* The role of reserving pages is that it allows the request to be
* noted as pending (the difference between committed and reserved
* indicates pending requests). If the request would exceed the
* page budget then the caller must poll in case a GC is necessary.
*
* @param pages The number of pages requested
* @return True if the page budget could satisfy the request.
*/
@Inline
public final boolean reservePages(int pages) {
lock();
required += adjustForMetaData(pages);
reserved = committed + required;
boolean satisfied = reserved <= pageBudget;
unlock();
return satisfied;
}
/**
* Remove a request to the space.
*
* @param pages The number of pages in the request.
*/
@Inline
public final void clearRequest(int pages) {
lock();
required -= adjustForMetaData(pages);
unlock();
}
/**
* Reserve pages unconditionally.<p>
*
* An example of where this is useful is in cases where it is
* desirable to put some space aside as head-room. By
* unconditionally reserving the pages, the pages are counted
* against the collectors budget. When the space is actually
* needed, the pages can be unconditionally released, freeing
* the pages for other purposes.
*
* @param pages The number of pages to be unconditionally
* reserved.
*/
public final void unconditionallyReservePages(int pages) {
lock();
committed += pages;
reserved += pages;
unlock();
}
/**
* Release pages unconditionally.<p>
*
* This call allows pages to be unconditionally removed from
* the collectors page budget.
*
* @see #unconditionallyReservePages
* @param pages The number of pages to be unconditionally
* released.
*/
public final void unconditionallyReleasePages(int pages) {
lock();
committed -= pages;
reserved -= pages;
unlock();
}
abstract Address allocPages(int pages);
/**
* Adjust a page request to include metadata requirements for a request
* of the given size. This must be a pure function, that is it does not
* depend on the state of the PageResource.
*
* @param pages The size of the pending allocation in pages
* @return The number of required pages, inclusive of any metadata
*/
public abstract int adjustForMetaData(int pages);
/**
* Allocate pages in virtual memory, returning zero on failure.<p>
*
* If the request cannot be satisfied, zero is returned and it
* falls to the caller to trigger the GC.
*
* Call <code>allocPages</code> (subclass) to find the pages in
* virtual memory. If successful then commit the pending page
* request and return the address of the first page.
*
* @param pages The number of pages requested
* @return The address of the first of <code>pages</code> pages, or
* zero on failure.
*/
@Inline
public final Address getNewPages(int pages) {
return allocPages(pages);
}
/**
* Commit pages to the page budget. This is called after
* successfully determining that the request can be satisfied by
* both the page budget and virtual memory. This simply accounts
* for the descrepency between <code>committed</code> and
* <code>reserved</code> while the request was pending.
*
* This *MUST* be called by each PageResource during the
* allocPages, and the caller must hold the lock.
*
* @param requestedPages The number of pages from this request
* @param totalPages The number of pages
*/
protected void commitPages(int requestedPages, int totalPages) {
int predictedPages = adjustForMetaData(requestedPages);
int delta = totalPages - predictedPages;
required -= predictedPages;
reserved += delta;
committed += totalPages;
if (!Plan.gcInProgress())
addToCommitted(totalPages); // only count mutator pages
}
/**
* Return the number of reserved pages
*
* @return The number of reserved pages.
*/
public final int reservedPages() { return reserved; }
/**
* Return the number of committed pages
*
* @return The number of committed pages.
*/
public final int committedPages() { return committed; }
/**
* Return the number of required pages
*
* @return The number of required pages.
*/
public final int requiredPages() { return required; }
/**
* Return the cumulative number of committed pages
*
* @return The cumulative number of committed pages.
*/
public static long cumulativeCommittedPages() { return cumulativeCommitted; }
/**
* Add to the total cumulative committed page count.
*
* @param pages The number of pages to be added.
*/
private static void addToCommitted(int pages) {
classLock.acquire();
cumulativeCommitted += pages;
classLock.release();
}
/**
* Acquire the appropriate lock depending on whether the context is
* GC or mutator.
*/
protected final void lock() {
if (Plan.gcInProgress())
gcLock.acquire();
else
mutatorLock.acquire();
}
/**
* Release the appropriate lock depending on whether the context is
* GC or mutator.
*/
protected final void unlock() {
if (Plan.gcInProgress())
gcLock.release();
else
mutatorLock.release();
}
}