/**
   * Add a new <code>SourceJob</code> for the <code>Source source</code>, with AST <code>ast</code>.
   * A new job will be created if needed. If the <code>Source source</code> has already been
   * processed, and its job discarded to release resources, then <code>null</code> will be returned.
   */
  public SourceJob addJob(Source source, Node ast) {
    Object o = jobs.get(source);
    SourceJob job = null;
    if (o == COMPLETED_JOB) {
      // the job has already been completed.
      // We don't need to add a job
      return null;
    } else if (o == null) {
      // No appropriate job yet exists, we will create one.

      job = this.createSourceJob(source, ast);

      // record the job in the map and the worklist.
      jobs.put(source, job);
      worklist.addLast(job);

      if (Report.should_report(Report.frontend, 3)) {
        Report.report(3, "Adding job for " + source + " at the " + "request of job " + currentJob);
      }
    } else {
      job = (SourceJob) o;
    }

    // if the current source job caused this job to load, record the
    // dependency.
    if (currentJob instanceof SourceJob) {
      ((SourceJob) currentJob).addDependency(source);
    }

    return job;
  }
  /**
   * Run all jobs in the work list (and any children they have) to completion. This method returns
   * <code>true</code> if all jobs were successfully completed. If all jobs were successfully
   * completed, then the worklist will be empty.
   *
   * <p>The scheduling of <code>Job</code>s uses two methods to maintain scheduling invariants:
   * <code>selectJobFromWorklist</code> selects a <code>SourceJob</code> from <code>worklist</code>
   * (a list of jobs that still need to be processed); <code>enforceInvariants</code> is called
   * before a pass is performed on a <code>SourceJob</code> and is responsible for ensuring all
   * dependencies are satisfied before the pass proceeds, i.e. enforcing any scheduling invariants.
   */
  public boolean runToCompletion() {
    boolean okay = true;

    while (okay && !worklist.isEmpty()) {
      SourceJob job = selectJobFromWorklist();

      if (Report.should_report(Report.frontend, 1)) {
        Report.report(1, "Running job " + job);
      }

      okay &= runAllPasses(job);

      if (job.completed()) {
        // the job has finished. Let's remove it from the map so it
        // can be garbage collected, and free up the AST.
        jobs.put(job.source(), COMPLETED_JOB);

        if (Report.should_report(Report.frontend, 1)) {
          Report.report(1, "Completed job " + job);
        }
      } else {
        // the job is not yet completed (although, it really
        // should be...)
        if (Report.should_report(Report.frontend, 1)) {
          Report.report(1, "Failed to complete job " + job);
        }
        worklist.add(job);
      }
    }

    if (Report.should_report(Report.frontend, 1))
      Report.report(1, "Finished all passes -- " + (okay ? "okay" : "failed"));

    return okay;
  }
 /** Adds a dependency from the current job to the given Source. */
 public void addDependencyToCurrentJob(Source s) {
   if (s == null) return;
   if (currentJob != null) {
     Object o = jobs.get(s);
     if (o != COMPLETED_JOB) {
       if (Report.should_report(Report.frontend, 2)) {
         Report.report(2, "Adding dependency from " + currentJob.source() + " to " + s);
       }
       currentJob.sourceJob().addDependency(s);
     }
   } else {
     throw new InternalCompilerError("No current job!");
   }
 }
  /**
   * 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;
          }
        }
      }
    }
  }