Coordinated Restore at Checkpoint Usage Guidelines

Adding the CRaC API

The library provided by org.crac is designed to provide a smooth CRaC adoption. Add this library to build an application that uses the CRaC API, to be able to run it on Java runtimes with CRaC, or without any implementation.

You can find the library in the Maven Repository.

 
<dependency>
  <groupId>org.crac</groupId>
  <artifactId>crac</artifactId>
  <version>${crac.version}</version>
</dependency>

 
implementation 'org.crac:crac:1.4.0'

Implementing the CRaC Resource

To use the API, you need to identify all classes in your code that are considered "resources": classes that must be notified when a checkpoint is about to be made and when a restore has happened. The API provides an eponymous interface, Resource, which must be implemented for the identified classes. There are only two methods, beforeCheckpoint() and afterRestore() which are used as callbacks by the JVM.

 
package my.app;

import org.crac.Context;
import org.crac.Core;
import org.crac.Resource;

public class MyClass implements Resource {

    public MyClass() {
        Core.getGlobalContext().register(this);
    }

    @Override
    public void beforeCheckpoint(Context<? extends Resource> context) {
        /* ... */
    }

    @Override
    public void afterRestore(Context<? extends Resource> context) {
        /* ... */
    }
}

The CRaC JavaDoc is available here.

Example use case:

The same applies to network connections, and you can also use the methods to deal with a sudden change in the system clock, which might impact things like cache timeouts.

All Resources in the application must be registered with the JVM, which can be achieved by obtaining a CRaC Context and using the register() method. Although you can create your own Context, the simplest way is to use the global Context obtained via the Core class’s static getGlobalContext() method.

It’s important to register the Resources in the right order because this order is used to call the beforeCheckpoint methods. However, the afterRestore methods are called in the opposite order. This approach simplifies things if there is a particular sequence in which things need to be prepared for a checkpoint; when restoring, there is a predictable inverse sequence.

The API also provides the Core.checkpointRestore() method to create a checkpoint programmatically within your application. You can add this call in the flow of your program, where you want the checkpoint to be created. The method returns when the restore is completed. This call can also be done with jcmd <PID or your_app.jar> JDK.checkpoint at any moment during the lifetime of your application, as described in Generating a Checkpoint further on this page.

Supported Platforms

Running CRaC on Linux

Version 17, 21, and 22 of Azul Zulu Builds of OpenJDK, with CRaC functionality, are available as of the release of April 2023. Only the bundles with -crac- in the name, have the integrated CRaC functionality.

 
$ sudo tar zxf <jdk>.tar.gz

 
java -XX:CRaCCheckpointTo=$HOME/crac-image/ -jar my_app.jar

 
jcmd my_app.jar JDK.checkpoint

 
java -XX:CRaCRestoreFrom=$HOME/crac-files/

Running CRaC in a Container (Docker)

Running CRaC on Windows or macOS

You can test your CRaC application on Windows or macOS with one of the following approaches:

Example With Compression

You can use the following test application to compare the impact of the compression:

 
public class TestCracCompression {
    static public void main(String[] args) throws InterruptedException {
        int cnt = 0;
        while (true) {
            System.out.println(cnt++);
            Thread.sleep(1000);
        }
    }
}

This is the output of the checkpoint creation without compression:

 
$ java -XX:CRaCCheckpointTo=cr TestCracCompression.java
...
$ jcmd -l | grep TestCracCompression
52794 jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher TestCracCompression.java
$ jcmd 52794 JDK.checkpoint
52794:
CR: Checkpoint ...
$ ls -sh cr/pages-1.img
49M cr/pages-1.img
$ java -XX:CRaCRestoreFrom=cr

This is the output of the checkpoint creation with compression:

 
$ java -XX:CRaCCheckpointTo=cr -XX:+CRaCImageCompression TestCracCompression.java
...
$ jcmd -l | grep TestCracCompression
53091 jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher TestCracCompression.java
$ jcmd 53091 JDK.checkpoint
53091:
CR: Checkpoint ...
$ ls -sh cr/pages-1.comp.img
12M cr/pages-1.comp.img
$ java -XX:CRaCRestoreFrom=cr

As you can see in the output above, the size of the checkpoint for this test application reduces from 49MB to 12MB.