Description Vasili Gulevich 2019-09-16 07:46:49 EDT

If a single org.eclipse.core.runtime.jobs.Job is scheduled multiple times, there are no guarantees on order of notifications received by IJobChangeListener.

For example, events may be observed in a following order:
- scheduled
- scheduled
- done
- done

This may confuse API user, as there is a strong guarantee on exclusive execution of a single Job instance.

Javadoc on org.eclipse.core.runtime.jobs.IJobChangeListener says:


> Listeners are notified of all job state changes, but whether the state change occurs before, during, or after listeners are notified is unspecified.


It is not clear from this description, that order of invocations for listeners themselves is also not guaranteed.

Please update Javadoc to reflect relaxed guarantees on listener execution order.

The importance of notification order can be illustrated by a naive example:

Job job = ...;

job.addJobChangeListener(new JobChangeAdapter() {
  private final AtomicReference<Object> resource = new AtomicReference<>();
  void scheduled(...) {
    resource.set(new Datum());
  }
  void done(...) {
    resource.get().update(); // Null pointer exception
    resource.set(null);
  }
});

job.schedule();
job.schedule();
job.schedule();