Package hudson.model

Class CheckPoint

java.lang.Object
hudson.model.CheckPoint
public final class CheckPoint extends Object
Provides a mechanism for synchronizing build executions in the face of concurrent builds.

At certain points of a build, BuildSteps and other extension points often need to refer to what happened in its earlier build. For example, a SCM check out can run concurrently, but the changelog computation requires that the check out of the earlier build has completed. Or if Hudson is sending out an e-mail, he needs to know the result of the previous build, so that he can decide an e-mail is necessary or not.

Check pointing is a primitive mechanism to provide this sort of synchronization. These methods can be only invoked from Executor threads.

Each CheckPoint instance represents unique check points. CheckPoint instances are normally created as a static instance, because two builds of the same project needs to refer to the same check point instance for synchronization to happen properly.

This class defines a few well-known check point instances. plugins can define their additional check points for their own use.

Note that not all job types support checkpoints.

Example

JUnitResultArchiver provides a good example of how a Recorder can depend on its earlier result.

Since:
1.319
Author:
Kohsuke Kawaguchi
See Also:

  • Field Details

  • Constructor Details

    • CheckPoint

      public CheckPoint(String internalName, Object identity)
      For advanced uses. Creates a check point that uses the given object as its identity.

    • CheckPoint

      public CheckPoint(String internalName)
      Parameters:
      internalName - Name of this check point that's used in the logging, stack traces, debug messages, and so on. This is not displayed to users. No need for i18n.

  • Method Details

    • equals

      public boolean equals(Object that)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • report

      public void report()
      Records that the execution of the build has reached to a check point, identified by the given identifier.

      If the successive builds are waiting for this check point, they'll be released.

      This method can be only called from an Executor thread.

    • block

      public void block() throws InterruptedException
      Waits until the previous build in progress reaches a check point, identified by the given identifier, or until the current executor becomes the youngest build in progress.

      Note that "previous build in progress" should be interpreted as "previous (build in progress)" instead of "(previous build) if it's in progress". This makes a difference around builds that are aborted or failed very early without reporting the check points. Imagine the following time sequence:

      1. Build #1, #2, and #3 happens around the same time
      2. Build #3 waits for check point JUnitResultArchiver
      3. Build #2 aborts before getting to that check point
      4. Build #1 finally checks in JUnitResultArchiver

      Using this method, build #3 correctly waits until the step 4. Because of this behavior, the report()/block() pair can normally be used without a try/finally block.

      This method can be only called from an Executor thread.

      Throws:
      InterruptedException - If the build (represented by the calling executor thread) is aborted while it's waiting.

    • block

      public void block(@NonNull BuildListener listener, @NonNull String waiter) throws InterruptedException
      Like block() but allows for richer logging.
      Parameters:
      listener - an optional listener to which
      waiter - a description of what component is requesting the wait, such as Descriptor.getDisplayName()
      Throws:
      InterruptedException - if the build is aborted while waiting
      Since:
      1.528