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:

BuildStep.getRequiredMonitorService()

Field Summary

Fields

Modifier and Type	Field	Description
static CheckPoint	COMPLETED	CheckPoint that indicates that the build is completed.
static CheckPoint	CULPRITS_DETERMINED	CheckPoint that indicates that AbstractBuild.getCulprits() is computed.
static CheckPoint	MAIN_COMPLETED	CheckPoint that indicates that the build has finished executing the "main" portion (Builders in case of FreeStyleProject) and now moving on to the post-build steps.

Constructor Summary

Constructors

Constructor	Description
CheckPoint(String internalName)
CheckPoint(String internalName, Object identity)	For advanced uses.

Method Summary

Modifier and Type	Method	Description
void	block()	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.
void	block(BuildListener listener, String waiter)	Like block() but allows for richer logging.
boolean	equals(Object that)
int	hashCode()
void	report()	Records that the execution of the build has reached to a check point, identified by the given identifier.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

CULPRITS_DETERMINED

public static final CheckPoint CULPRITS_DETERMINED

CheckPoint that indicates that AbstractBuild.getCulprits() is computed.

COMPLETED

public static final CheckPoint COMPLETED

CheckPoint that indicates that the build is completed. (Run.isBuilding()==false)

MAIN_COMPLETED

public static final CheckPoint MAIN_COMPLETED

CheckPoint that indicates that the build has finished executing the "main" portion (Builders in case of FreeStyleProject) and now moving on to the post-build steps.

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

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