Package hudson.model

Class 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:
    BuildStep.getRequiredMonitorService()
    • Constructor Detail

      • 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 Detail

      • hashCode

        public int hashCode()
        Overrides:
        hashCode 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.