Package edu.rit.pj

Class LongSchedule

java.lang.Object
edu.rit.pj.Schedule
edu.rit.pj.LongSchedule
public abstract class LongSchedule extends Schedule
Class LongSchedule provides an object that determines how to schedule the iterations of a ParallelForLoop among the threads in a ParallelTeam. The loop index is type long.

To create a schedule object, call one of the following static methods:

  • LongSchedule.fixed()
  • LongSchedule.dynamic()
  • LongSchedule.guided()
  • LongSchedule.runtime()
  • LongSchedule.parse()

The Parallel Java Library includes three built-in schedule implementations: fixed, dynamic, and guided. You can create instances of these by calling the fixed(), dynamic(), and guided() methods. You can also create your own schedule implementation by writing a subclass of class LongSchedule. The subclass must have a no-argument constructor and a constructor whose argument is an array of Strings; see the parse() method for further information about how these constructors are used.

Version:
18-Nov-2009
Author:
Alan Kaminsky

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    LongSchedule()
    Construct a new schedule object.

  • Method Summary

    Modifier and Type
    Method
    Description
    static LongSchedule
    dynamic()
    Returns a dynamic schedule object with a chunk size of 1.
    static LongSchedule
    dynamic(long theChunkSize)
    Returns a dynamic schedule object with the given chunk size.
    static LongSchedule
    fixed()
    Returns a fixed schedule object.
    static LongSchedule
    guided()
    Returns a self-guided schedule object with a minimum chunk size of 1.
    static LongSchedule
    guided(long theChunkSize)
    Returns a self-guided schedule object with the given minimum chunk size.
    abstract boolean
    isFixedSchedule()
    Determine if this schedule is a fixed schedule.
    abstract LongRange
    next(int theThreadIndex)
    Obtain the next chunk of iterations for the given thread index.
    static LongSchedule
    parse(String s)
    Returns a schedule object of a type determined by parsing the given string.
    static LongSchedule
    runtime()
    Returns a schedule object of a type determined at run time.
    static LongSchedule
    runtime(LongSchedule defaultSchedule)
    Returns a schedule object of a type determined at run time, using the given default schedule.
    abstract void
    start(int K, LongRange theLoopRange)
    Start generating chunks of iterations for a parallel for loop using this schedule.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • LongSchedule

      protected LongSchedule()
      Construct a new schedule object.

  • Method Details

    • fixed

      public static LongSchedule fixed()
      Returns a fixed schedule object. The loop iterations are apportioned among the parallel team threads once at the beginning of the parallel for loop, with each thread getting a fixed number of iterations, the same number of iterations for each thread (plus or minus one).
      Returns:
      Fixed schedule object.

    • dynamic

      public static LongSchedule dynamic()
      Returns a dynamic schedule object with a chunk size of 1. The loop iterations are apportioned into chunks of size 1 (one iteration per chunk). Each parallel team thread repeatedly performs the next available iteration until there are no more iterations.
      Returns:
      Dynamic schedule object.

    • dynamic

      public static LongSchedule dynamic(long theChunkSize)
      Returns a dynamic schedule object with the given chunk size. The loop iterations are apportioned into chunks of size theChunkSize (theChunkSize iterations per chunk). Each parallel team thread repeatedly performs the next available chunk of iterations until there are no more chunks. The final chunk may be smaller than theChunkSize.
      Parameters:
      theChunkSize - Chunk size, >= 1.
      Returns:
      Dynamic schedule object.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theChunkSize < 1.

    • guided

      public static LongSchedule guided()
      Returns a self-guided schedule object with a minimum chunk size of 1. The loop iterations are apportioned into chunks of exponentially diminishing sizes. Each successive chunk's size is half the remaining number of iterations divided by the number of threads in the parallel team. However, each chunk's size is at least 1 (a minimum of one iteration per chunk). Each parallel team thread repeatedly performs the next available chunk of iterations until there are no more chunks.
      Returns:
      Self-guided schedule object.

    • guided

      public static LongSchedule guided(long theChunkSize)
      Returns a self-guided schedule object with the given minimum chunk size. The loop iterations are apportioned into chunks of exponentially diminishing sizes. Each successive chunk's size is half the remaining number of iterations divided by the number of threads in the parallel team. However, each chunk is at least theChunkSize (a minimum of theChunkSize iterations per chunk). Each parallel team thread repeatedly performs the next available chunk of iterations until there are no more chunks. The final chunk may be smaller than theChunkSize.
      Parameters:
      theChunkSize - Minimum chunk size, >= 1.
      Returns:
      Self-guided schedule object.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theChunkSize < 1.

    • runtime

      public static LongSchedule runtime()
      Returns a schedule object of a type determined at run time. If the "pj.schedule" Java property is specified, the property's value is parsed by the parse() method, and that gives the type of schedule. If the "pj.schedule" Java property is not specified, the default is a fixed schedule. You can specify the schedule on the Java command line like this (note that quotation marks may be needed): 
       java -Dpj.schedule="dynamic(5)" . . .
      Returns:
      Schedule object.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if the "pj.schedule" property value cannot be parsed.

    • runtime

      public static LongSchedule runtime(LongSchedule defaultSchedule)
      Returns a schedule object of a type determined at run time, using the given default schedule. If the "pj.schedule" Java property is specified, the property's value is parsed by the parse() method, and that gives the type of schedule. If the "pj.schedule" Java property is not specified, the given defaultSchedule is returned. You can specify the schedule on the Java command line like this (note that quotation marks may be needed): 
       java -Dpj.schedule="dynamic(5)" . . .
      Parameters:
      defaultSchedule - Schedule to use if the "pj.schedule" Java property is not specified.
      Returns:
      Schedule object.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if the "pj.schedule" property value cannot be parsed.

    • parse

      public static LongSchedule parse(String s)
      Returns a schedule object of a type determined by parsing the given string. The string must be one of the following:
      • "fixed" -- Fixed schedule.
      • "dynamic" -- Dynamic schedule with a chunk size of 1.
      • "dynamic(n)" -- Dynamic schedule with a chunk size of n, an integer >= 1.
      • "guided" -- Self-guided schedule with a minimum chunk size of 1.
      • "guided(n)" -- Self-guided schedule with a minimum chunk size of n, an integer >= 1.
      • "classname" -- Schedule that is an instance of the given class. classname is the fully-qualified class name of the schedule class, which must be a subclass of class LongSchedule. The instance is constructed using the subclass's no-argument constructor.
      • "classname(arg,arg,...)" -- Schedule that is an instance of the given class. classname is the fully-qualified class name of the schedule class, which must be a subclass of class LongSchedule. The arguments between the parentheses are split into separate strings separated by commas. There cannot be parentheses or commas within the arguments themselves. The instance is constructed using the subclass's constructor whose argument is an array of Strings, namely the individual arguments between the parentheses.
      Parameters:
      s - String to parse.
      Returns:
      Schedule object.
      Throws:
      NullPointerException - (unchecked exception) Thrown if s is null.
      IllegalArgumentException - (unchecked exception) Thrown if s is not one of the above.

    • isFixedSchedule

      public abstract boolean isFixedSchedule()
      Determine if this schedule is a fixed schedule. For a parallel team with K threads, a fixed schedule partitions the loop index range into exactly K chunks, one chunk for each thread, each chunk with predetermined upper and lower bounds.
      Returns:
      True if this is a fixed schedule, false otherwise.

    • start

      public abstract void start(int K, LongRange theLoopRange)
      Start generating chunks of iterations for a parallel for loop using this schedule.

      The start() method is only called by a single thread in the Parallel Java middleware.

      Parameters:
      K - Number of threads in the parallel team.
      theLoopRange - Range of iterations for the entire parallel for loop. The stride may be 1 or greater.

    • next

      public abstract LongRange next(int theThreadIndex)
      Obtain the next chunk of iterations for the given thread index. If there are more iterations, a range object is returned whose lower bound, upper bound, and stride specify the chunk of iterations to perform. The returned range object's stride is the same as that given to the start() method. The returned range object's lower bound and upper bound are contained within the range given to the start() method. If there are no more iterations, null is returned.

      The next() method is called by multiple parallel team threads in the Parallel Java middleware. The next() method must be multiple thread safe.

      Parameters:
      theThreadIndex - Thread index in the range 0 .. K-1.
      Returns:
      Chunk of iterations, or null if no more iterations.