/**
   * Insert the list of <code>newPasses</code> into <code>passes</code> immediately after the pass
   * named <code>id</code>.
   */
  public void afterPass(List passes, Pass.ID id, List newPasses) {
    for (ListIterator i = passes.listIterator(); i.hasNext(); ) {
      Pass p = (Pass) i.next();

      if (p.id() == id) {
        for (Iterator j = newPasses.iterator(); j.hasNext(); ) {
          i.add(j.next());
        }

        return;
      }
    }

    throw new InternalCompilerError("Pass " + id + " not found.");
  }
  /**
   * Insert the list of <code>newPasses</code> into <code>passes</code> immediately before the pass
   * named <code>id</code>.
   */
  public void beforePass(List passes, Pass.ID id, List newPasses) {
    for (ListIterator i = passes.listIterator(); i.hasNext(); ) {
      Pass p = (Pass) i.next();

      if (p.id() == id) {
        // Backup one position.
        i.previous();

        for (Iterator j = newPasses.iterator(); j.hasNext(); ) {
          i.add(j.next());
        }

        return;
      }
    }

    throw new InternalCompilerError("Pass " + id + " not found.");
  }
  /**
   * Replace the pass named <code>id</code> in <code>passes</code> with the list of <code>newPasses
   * </code>.
   */
  public void replacePass(List passes, Pass.ID id, List newPasses) {
    for (ListIterator i = passes.listIterator(); i.hasNext(); ) {
      Pass p = (Pass) i.next();

      if (p.id() == id) {
        if (p instanceof BarrierPass) {
          throw new InternalCompilerError("Cannot replace a barrier pass.");
        }

        i.remove();

        for (Iterator j = newPasses.iterator(); j.hasNext(); ) {
          i.add(j.next());
        }

        return;
      }
    }

    throw new InternalCompilerError("Pass " + id + " not found.");
  }
  /**
   * Get the sub-list of passes for the job between passes <code>begin</code> and <code>end</code>,
   * inclusive.
   */
  public List passes(Job job, Pass.ID begin, Pass.ID end) {
    List l = passes(job);
    Pass p = null;

    Iterator i = l.iterator();

    while (i.hasNext()) {
      p = (Pass) i.next();
      if (begin == p.id()) break;
      if (!(p instanceof BarrierPass)) i.remove();
    }

    while (p.id() != end && i.hasNext()) {
      p = (Pass) i.next();
    }

    while (i.hasNext()) {
      p = (Pass) i.next();
      i.remove();
    }

    return l;
  }
  /**
   * Before running <code>Pass pass</code> on <code>SourceJob job</code> make sure that all
   * appropriate scheduling invariants are satisfied, to ensure that all passes of other jobs that
   * <code>job</code> depends on will have already been done.
   */
  protected void enforceInvariants(Job job, Pass pass) throws CyclicDependencyException {
    SourceJob srcJob = job.sourceJob();
    if (srcJob == null) {
      return;
    }

    BarrierPass lastBarrier = srcJob.lastBarrier();
    if (lastBarrier != null) {
      // make sure that _all_ dependent jobs have completed at least up to
      // the last barrier (not just children).
      //
      // Ideally the invariant should be that only the source jobs that
      // job _depends on_ should be brought up to the last barrier.
      // This is work to be done in the future...
      List allDependentSrcs = new ArrayList(srcJob.dependencies());
      Iterator i = allDependentSrcs.iterator();
      while (i.hasNext()) {
        Source s = (Source) i.next();
        Object o = jobs.get(s);
        if (o == COMPLETED_JOB) continue;
        if (o == null) {
          throw new InternalCompilerError("Unknown source " + s);
        }
        SourceJob sj = (SourceJob) o;
        if (sj.pending(lastBarrier.id())) {
          // Make the job run up to the last barrier.
          // We ignore the return result, since even if the job
          // fails, we will keep on going and see
          // how far we get...
          if (Report.should_report(Report.frontend, 3)) {
            Report.report(3, "Running " + sj + " to " + lastBarrier.id() + " for " + srcJob);
          }
          runToPass(sj, lastBarrier.id());
        }
      }
    }

    if (pass instanceof GlobalBarrierPass) {
      // need to make sure that _all_ jobs have completed just up to
      // this global barrier.

      // If we hit a cyclic dependency, ignore it and run the other
      // jobs up to that pass.  Then try again to run the cyclic
      // pass.  If we hit the cycle again for the same job, stop.
      LinkedList barrierWorklist = new LinkedList(jobs.values());

      while (!barrierWorklist.isEmpty()) {
        Object o = barrierWorklist.removeFirst();
        if (o == COMPLETED_JOB) continue;
        SourceJob sj = (SourceJob) o;
        if (sj.completed(pass.id()) || sj.nextPass() == sj.passByID(pass.id())) {
          // the source job has either done this global pass
          // (which is possible if the job was loaded late in the
          // game), or is right up to the global barrier.
          continue;
        }

        // Make the job run up to just before the global barrier.
        // We ignore the return result, since even if the job
        // fails, we will keep on going and see
        // how far we get...
        Pass beforeGlobal = sj.getPreviousTo(pass.id());
        if (Report.should_report(Report.frontend, 3)) {
          Report.report(3, "Running " + sj + " to " + beforeGlobal.id() + " for " + srcJob);
        }

        // Don't use runToPass, since that catches the
        // CyclicDependencyException that we should report
        // back to the caller.
        while (!sj.pendingPasses().isEmpty()) {
          Pass p = (Pass) sj.pendingPasses().get(0);

          runPass(sj, p);

          if (p == beforeGlobal) {
            break;
          }
        }
      }
    }
  }