ptolemy.graph.sched
Class Schedule

java.lang.Object
  ptolemy.graph.sched.ScheduleElement
      ptolemy.graph.sched.Schedule

public class Schedule
extends ScheduleElement

This class represents a static schedule of firing elements invocation. An instance of this class is returned by the scheduler of a model to represent order of firing element firings in the model. A schedule consists of a list of schedule elements and the number of times the schedule should repeat (called the iteration count).

Each element of the schedule is represented by an instance of the ScheduleElement class. Each element may correspond to a number of firings of a single firing element (represented by the Firing class) or an entire sub-schedule (represented by a hierarchically contained instance of this class). This nesting allows this concise representation of looped schedules. The nesting can be arbitrarily deep, but must be a tree where the leaf nodes represent firings. It is up to the scheduler to enforce this requirement.

The add() and remove() methods are used to add or remove schedule elements. Only elements of type ScheduleElement (Schedule or Firing) may be added to the schedule list. The iteration count is set by the setIterationCount() method. If this method is not invoked, a default value of one will be used.

As an example, suppose that we have an SDF graph containing actors A, B, C, and D, with the firing order ABCBCBCDD. This firing order can be represented by a simple looped schedule. The code to create this schedule appears below.

       Schedule S = new Schedule();
       Firing S1 = new Firing();
       Schedule S2 = new Schedule();
       Firing S3 = new Firing();
       S.add(S1);
       S.add(S2);
       S.add(S3);
       S1.setFiringElement(A);
       S2.setIterationCount(3);
       Firing S2_1 = new Firing();
       Firing S2_2 = new Firing();
       S2_1.setFiringElement(B);
       S2_2.setFiringElement(C);
       S2.add(S2_1);
       S2.add(S2_2);
       S3.setIterationCount(2);
       S3.setFiringElement(D);
 

Note that this implementation is not synchronized. It is therefore not safe for a thread to make modifications to the schedule structure while multiple threads are concurrently accessing the schedule.

References

S. S. Bhattacharyya, P K. Murthy, and E. A. Lee, Software Syntheses from Dataflow Graphs, Kluwer Academic Publishers, 1996.

Since:

Ptolemy II 4.0

Version:

$Id: Schedule.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Shahrooz Shahparnia, Mingyung Ko, University of Maryland at College Park, based on a file by Brian K. Vogel, Steve Neuendorffer

See Also:

Firing, Schedule, ScheduleElement

Accepted Rating:

red (ssb)

Proposed Rating:

red (shahrooz)

Nested Class Summary

private class	Schedule.FiringElementIterator An adapter class for iterating over the firing elements of this schedule.
private class	Schedule.FiringIterator An adapter class for iterating over the firings of this schedule.

Field Summary

private java.util.Map	_firingElementFiringsMap
private java.util.List	_firingInstancesList
protected java.util.List	_schedule The list of schedule elements contained by this schedule.
private int	_treeDepth

Fields inherited from class ptolemy.graph.sched.ScheduleElement

_parent

Constructor Summary

Schedule()
Construct a schedule with iteration count of one and an empty schedule list.

Schedule(java.lang.Class firingElementClass)
Construct a schedule with iteration count of one and an empty schedule list.

Method Summary

private java.util.Map	_getFiringElementFiringsMap()
private java.util.List	_getFiringInstancesList()
void	add(int index, ScheduleElement element) Insert the specified schedule element at the specified position in the schedule list.
void	add(ScheduleElement element) Append the specified schedule element to the end of the schedule list.
int	appearanceCount(java.lang.Object firingElement) The number of times the given firing element appears in the schedule.
java.util.Iterator	firingElementIterator() Return the firing element invocation sequence of the schedule in the form of a sequence of firing elements.
java.util.Iterator	firingIterator() Return the Firing invocation sequence of this schedule in the form of a sequence of firings.
java.util.List	firings(java.lang.Object firingElement) Get firings for the firing element.
ScheduleElement	get(int index) Return the element at the specified position in the list.
java.util.Iterator	iterator() Return an iterator over the schedule elements of this schedule.
java.util.List	lexicalOrder() Get the lexical order of firing elements.
int	maxAppearanceCount() Get the maximum appearance counts of all firing elements in the schedule.
ScheduleElement	remove(int index) Remove the schedule element at the specified position in the schedule list.
int	size() Return the number of elements in this list.
java.lang.String	toParenthesisString(java.util.Map nameMap, java.lang.String delimiter) Print the schedule in a nested parenthesis style.
java.lang.String	toString() Output a string representation of this Schedule.

Methods inherited from class ptolemy.graph.sched.ScheduleElement

_getVersion, _incrementVersion, firingElementClass, getIterationCount, getParent, setIterationCount, setParent, toParenthesisString

Methods inherited from class java.lang.Object

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

Field Detail

_schedule

protected java.util.List _schedule

The list of schedule elements contained by this schedule.

_treeDepth

private int _treeDepth

_firingInstancesList

private java.util.List _firingInstancesList

_firingElementFiringsMap

private java.util.Map _firingElementFiringsMap

Constructor Detail

Schedule

public Schedule()

Construct a schedule with iteration count of one and an empty schedule list. This constructor should be used when creating a root schedule.

Schedule

public Schedule(java.lang.Class firingElementClass)

Construct a schedule with iteration count of one and an empty schedule list. This constructor should be used when creating a root schedule. If this constructor is used, ScheduleElements containing firing elements of the given class would only be accepted as next elements for this schedule.

Parameters:

firingElementClass - The given class type.

Method Detail

add

public void add(ScheduleElement element)

Append the specified schedule element to the end of the schedule list. This element must be an instance of ScheduleElement.

Parameters:

element - The schedule element to add.

add

public void add(int index,
                ScheduleElement element)

Insert the specified schedule element at the specified position in the schedule list. This element must be an instance of ScheduleElement. An exception is thrown if the index is out of range.

Parameters:

index - The index at which the specified element is to be inserted.

element - The schedule element to add.

Throws:

java.lang.IndexOutOfBoundsException - If the specified index is out of range (index < 0 || index > size()).

appearanceCount

public int appearanceCount(java.lang.Object firingElement)

The number of times the given firing element appears in the schedule. Generally, firing elements represent program blocks. Appearances of elements indicate how many copies of codes are in the schedule. The more appearances, the larger program space is required.

Parameters:

firingElement - The given firing element.

Returns:

The number of appearances.

firingElementIterator

public java.util.Iterator firingElementIterator()

Return the firing element invocation sequence of the schedule in the form of a sequence of firing elements. For a valid schedule, all of the lowest-level nodes should be an instance of Firing. If the schedule is not valid, then the returned iterator will contain null elements.

A runtime exception is thrown if the underlying schedule structure is modified while the iterator is active.

Specified by:

firingElementIterator in class ScheduleElement

Returns:

An iterator over a sequence of firing elements.

Throws:

java.util.ConcurrentModificationException - If the underlying schedule structure is modified while the iterator is active.

firingIterator

public java.util.Iterator firingIterator()

Return the Firing invocation sequence of this schedule in the form of a sequence of firings. All of the lowest-level nodes of the schedule should be an instance of Firing. Otherwise an exception will occur at some point in the iteration.

A runtime exception is thrown if the underlying schedule structure is modified while the iterator is active.

Implementation note: This method is optimized to be memory efficient. It walks the schedule tree structure as the iterator methods are invoked.

Specified by:

firingIterator in class ScheduleElement

Returns:

An iterator over a sequence of firings.

Throws:

java.util.ConcurrentModificationException - If the underlying schedule structure is modified while the iterator is active.

firings

public java.util.List firings(java.lang.Object firingElement)

Get firings for the firing element. This is used in determining element appearances.

Parameters:

firingElement - The given firing element.

Returns:

A list of firings for the firing element.

get

public ScheduleElement get(int index)

Return the element at the specified position in the list.

Parameters:

index - The index of the element to return.

Returns:

The element at the specified position in the list.

iterator

public java.util.Iterator iterator()

Return an iterator over the schedule elements of this schedule. The ordering of elements in the iterator sequence is the order of the schedule list. The elements of the iterator sequence are instances of Firing or Schedule.

A runtime exception is thrown if the underlying schedule structure is modified while the iterator is active.

Returns:

An iterator over the schedule elements of this schedule.

Throws:

java.util.ConcurrentModificationException - If the underlying schedule structure is modified while the iterator is active.

lexicalOrder

public java.util.List lexicalOrder()

Get the lexical order of firing elements. Only single appearance schedules are qualified for this operation. It's meaningless to have the order for multiple appearance schedules.

Returns:

The lexical order of firing elements.

Throws:

java.lang.IllegalStateException - If this is not a single appearance schedule.

maxAppearanceCount

public int maxAppearanceCount()

Get the maximum appearance counts of all firing elements in the schedule.

Returns:

The maximum appearance counts.

remove

public ScheduleElement remove(int index)

Remove the schedule element at the specified position in the schedule list.

Parameters:

index - The index of the schedule element to be removed.

Returns:

The schedule element that was removed.

size

public int size()

Return the number of elements in this list.

Returns:

The number of elements in this list.

toParenthesisString

public java.lang.String toParenthesisString(java.util.Map nameMap,
                                            java.lang.String delimiter)

Print the schedule in a nested parenthesis style. Please see ScheduleElement.toParenthesisString(Map, String).

Specified by:

toParenthesisString in class ScheduleElement

Parameters:

nameMap - The map from firing elements to their short names.

delimiter - The delimiter between iterands.

Returns:

A nested parenthesis expression of the schedule.

toString

public java.lang.String toString()

Output a string representation of this Schedule.

Overrides:

toString in class java.lang.Object

Returns:

Return a string representation of this Schedule.

_getFiringInstancesList

private java.util.List _getFiringInstancesList()

_getFiringElementFiringsMap

private java.util.Map _getFiringElementFiringsMap()