Initial commit

.github/workflows/hugo.yaml

@@ -0,0 +1,31 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true or recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: 'latest'
+          extended: true
+
+      - name: Build
+        run: hugo --minify
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

.gitignore

@@ -0,0 +1,2 @@
+.idea/
+/.hugo_build.lock

README.md

@@ -0,0 +1,15 @@
+# CRaC Documentation
+
+This repository contains the sources of the CRaC documentation that is provided on [crac.org](http://crac.org/).
+
+## Static Website Generation
+
+* The website is generated with [Hugo](https://gohugo.io/).
+* The theme is [Relearn](https://mcshelby.github.io/hugo-theme-relearn/index.html).
+* The website is built and published to GitHub Pages with a GitHub Action.
+
+### Run Locally
+
+* Install Hugo, on macOS: `brew install hugo`.
+* Run the website with `hugo serve`.
+* The website is available on [localhost:1313](http://localhost:1313/).

archetypes/default.md

@@ -0,0 +1,5 @@
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++

content/_index.md

@@ -0,0 +1,115 @@
++++
+title = "Coordinated Restore at Checkpoint"
+weight = 1
++++
+
+{{% notice style="blue" title="What is CRaC?" icon="java" %}}
+Coordinated Restore at Checkpoint (CRaC) is a JDK project that allows you to start Java programs with a shorter time to first transaction, combined with less time and resources to achieve full code speed.
+{{% /notice %}}
+
+<div style="text-align: center">
+
+{{% button href="/use/implement-crac/" style="blue" icon="fas fa-github" %}}CRaC IN YOUR CODE{{% /button %}}
+{{% button href="/use/checkpoint-and-restore/" style="blue" icon="rocket" %}}USING CRaC{{% /button %}}
+
+{{% button href="https://github.com/CRaC/org.crac/tags" style="blue" icon="bookmark" %}}CRaC API 1.4.0 NOW AVAILABLE{{% /button %}}
+
+## Why CRaC?
+
+The CRaC (Coordinated Restore at Checkpoint) Project researches the coordination of Java programs with mechanisms to checkpoint (make an image of, snapshot) a Java instance while executing. Restoring from the image could solve some of the problems with the start-up and warm-up times. The primary aim of the Project is to develop a new standard mechanism-agnostic API to notify Java programs about the checkpoint and restore events. Other research activities will include, but will not be limited to, integration with existing checkpoint/restore mechanisms and development of new ones, changes to JVM and JDK to make images smaller and ensure they are correct.
+
+## USED BY
+
+<div style="display: flex; justify-content: space-between;">
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<img src="/images/logo/spring.png" height="50px" />
+<span style="font-weight: bold; font-size: 1.4em;">Spring Boot</span>
+<br/><br/>
+
+{{% button href="https://github.com/CRaC/example-spring-boot" style="blue" icon="github" %}}Example project{{% /button %}}
+
+[More info](/frameworks/spring-boot/)
+
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<img src="/images/logo/quarkus.svg" height="50px" />
+<span style="font-weight: bold; font-size: 1.4em;">Quarkus</span>
+<br/><br/>
+
+{{% button href="https://github.com/CRaC/example-quarkus" style="blue" icon="github" %}}Example project{{% /button %}}
+
+[More info](/frameworks/quarkus/)
+
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<img src="/images/logo/micronaut.webp" height="50px" />
+<span style="font-weight: bold; font-size: 1.4em;">Micronaut</span>
+<br/><br/>
+
+{{% button href="https://github.com/CRaC/example-micronaut" style="blue" icon="git" %}}Example project{{% /button %}}
+
+[More info](/frameworks/micronaut/)
+
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<img src="/images/logo/aws-lambda.webp" height="50px" />
+<span style="font-weight: bold; font-size: 1.4em;">AWS Lambda</span>
+<br/><br/>
+
+{{% button href="https://github.com/CRaC/example-lambda" style="blue" icon="github" %}}Example project{{% /button %}}
+
+[More info](/frameworks/aws-lambda/)
+
+</span>
+</div>
+
+## Features
+
+<div style="display: flex; justify-content: space-between;">
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<span style="font-weight: bold; font-size: 1.4em;">Super fast startup</span>
+<br/><br/>
+Startup within milliseconds from a checkpoint.
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<span style="font-weight: bold; font-size: 1.4em;">Checkpoint creation</span>
+<br/><br/>
+Generate checkpoints from code or with jcmd.
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<span style="font-weight: bold; font-size: 1.4em;">Restore from checkpoint</span>
+<br/><br/>
+Restore on the same machine, or many others from a checkpoint.
+
+</div>
+
+<div style="display: flex; justify-content: space-between;">
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<span style="font-weight: bold; font-size: 1.4em;">Minimal code changes</span>
+<br/><br/>
+Use frameworks, or implement the CRaC API to assist in the creation and restore of checkpoints
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<span style="font-weight: bold; font-size: 1.4em;">Framework support</span>
+<br/><br/>
+Several frameworks (Spring Boot, Quarkus, Micronaut,...) offer CRaC support out-of-the-box.
+</span>
+
+<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
+<span style="font-weight: bold; font-size: 1.4em;">Use it in the Cloud</span>
+<br/><br/>
+AWS Lambda has CRaC functionality integrated, no code changes needed!
+</span>
+
+</div>
+
+</div>

content/about/_index.md

@@ -0,0 +1,8 @@
++++
+title = "About CRaC"
+weight = 10
++++
+
+Several frameworks provide CRaC functionality out-of-the-box.
+
+{{% children sort="weight" %}}

content/about/about-crac.md

@@ -0,0 +1,96 @@
++++
+title = "What is Coordinated Restore at Checkpoint?"
+weight = 11
++++
+
+Coordinated Restore at Checkpoint (CRaC) is an OpenJDK feature that provides a fast start and immediate performance for Java applications.
+
+A Java application and JVM are started from an image in a warmed-up form.
+The image is created from a running Java instance at arbitrary point of time ("checkpoint").
+The start from the image ("restore") continues from the point when checkpoint was made.
+
+The restore in general is faster than initialization.
+After the restore, Java runtime performance is also on-par with the one at the checkpoint.
+So, after proper warm-up before the checkpoint, restored Java instance is able to deliver the best runtime characteristics immediately.
+
+Coordinated Restore undisruptively introduces new before-checkpoint and after-restore phases in Java application lifecycle.
+In contrast with uncoordinated checkpoint/restore, coordination allows restored Java applications to behave differently.
+For example, it is possible to react on changes in execution environment that happened since checkpoint was done.
+
+CRaC implementation creates the checkpoint only if the whole Java instance state can be stored in the image.
+Resources like open files or sockets are cannot, so it is required to release them when checkpoint is made.
+CRaC emits notifications for an application to prepare for the checkpoint and return to operating state after restore.
+
+With more Java frameworks and libraries adopting CRaC, applications can benefit with little or no changes in the code.
+Moreover, the required amount of changes in the resource management code tends to be small, see examples below.
+
+Coordinated Restore is not tied to a particular checkpoint/restore implementation and will able to use existing ones (CRIU, docker checkpoint/restore) and ones yet to be developed.
+
+
+### CPU Features
+
+When running checkpoint and restore on different computers you may seen an error message during restore
+
+```
+You have to specify -XX:CPUFeatures=[...] together with -XX:CRaCCheckpointTo when making a checkpoint file; specified -XX:CRaCRestoreFrom file contains CPU features [...]; missing features of this CPU are [...]
+```
+
+See [more details about the CPU Features configuration](cpu-features.md).
+
+## Programmer's flow
+
+Programs may need to be adjusted for use with Coordinated Restore at Checkpoint.
+
+A [step-by-step guide](STEP-BY-STEP.md) and [best practices guide](best-practices.md) provide information on how to implement the CRaC support in the code.
+
+Another option is to use an existing framework with CRaC support.
+
+No changes required:
+* Micronaut: https://github.com/CRaC/example-micronaut
+* Quarkus Hello World: https://github.com/CRaC/example-quarkus
+* Spring Boot: https://github.com/CRaC/example-spring-boot
+
+With configuration changes:
+* [Quarkus Super Heroes migration](super-heroes.md) shows a walkthrough for making an existing non-trivial Quarkus application CRaC-able.
+
+### API
+
+The CRaC API is not a part of Java SE specification.
+We hope that eventually it will be there, until then there are different packages that can be used.
+
+#### `jdk.crac`
+
+* [javadoc](https://crac.github.io/jdk/jdk-crac/api/java.base/jdk/crac/package-summary.html)
+
+This is the API that is implemented in the [CRaC JDK](#JDK).
+
+Please refer to [`org.crac`](#orgcrac) if you are looking to add CRaC support to a code that should also work on a regular JDK/JRE.
+
+#### `org.crac`
+
+The package is provided by [org.crac](https://github.com/org-crac/org.crac) compatibility library.
+
+The org.crac is designed to provide smooth CRaC adoption.
+Users of the library can build against and use CRaC API on Java runtimes with `jdk.crac`, `javax.crac`, or without any implementation.
+* In compile-time, `org.crac` package totally mirrors `jdk.crac` and `javax.crac`.
+* In runtime, org.crac uses reflection to detect CRaC implementation.
+If the one is available, all requests to `org.crac` are passed to the implementation.
+Otherwise, requests are forwarded to a dummy implementation.
+
+The dummy implementation allows an application to run but not to use CRaC:
+* resources can be registered for notification,
+* checkpoint request fails with an exception.
+
+
+## Implementation details
+
+Current OpenJDK implementation is based on using the CRIU project to create the image.
+
+[CRIU](https://github.com/CRaC/criu) hosts a few changes made to improve CRaC usability.
+
+You can read more about debugging C/R issues in your application in the [debug guide](./debugging.md).
+
+## Workarounds
+
+Sometimes it might be difficult to alter the application to properly coordinate with the checkpoint (e.g. due to a code in a library you cannot modify). As a temporary workaround you can [configure file-descriptor policies](./fd-policies.md).
+

content/about/jdk-project.md

@@ -0,0 +1,22 @@
++++
+title = "OpenJDK CRaC Project"
+weight = 13
++++
+
+OpenJDK CRaC Project is developed in https://github.com/openjdk/crac.
+
+Latest release can be found in https://crac.github.io/openjdk-builds.
+
+```sh
+$ sudo tar zxf <jdk>.tar.gz
+```
+
+**NOTE**: The JDK archive should be extracted with `sudo`.
+
+When using CRaC, if you see an "Operation not permitted" error, you may have to update your `criu` permissions with:
+
+```sh
+sudo chown root:root $JAVA_HOME/lib/criu
+sudo chmod u+s $JAVA_HOME/lib/criu
+```
+

content/about/results.md

@@ -0,0 +1,61 @@
++++
+title = "Startup Improvement Results"
+weight = 12
++++
+
+CRaC support was implemented in a few frameworks with the following results.
+The source code can be found in the [Projects with CRaC support](#projects-with-crac-support) section.
+
+<details><summary>The environment</summary>
+<p>
+
+* laptop with Intel i7-5500U, 16Gb RAM and SSD.
+* Linux kernel 5.7.4-arch1-1
+* data was collected in container running `ubuntu:18.04` based image
+* host operating system: archlinux
+
+[jdk14-crac build](https://github.com/org-crac/jdk/releases/tag/release-jdk-crac)
+
+---
+</p>
+</details>
+
+<details><summary>How to reproduce</summary>
+<p>
+
+To reproduce you need to create a workspace directory and clone along next repositories:
+* [utils](https://github.com/org-crac/utils)
+* [docs](https://github.com/org-crac/docs) (this repo)
+* [example-spring-boot](https://github.com/org-crac/example-spring-boot)
+* [example-quarkus](https://github.com/org-crac/example-quarkus)
+* [example-micronaut](https://github.com/org-crac/example-micronaut)
+* [example-xml-transform](https://github.com/org-crac/example-xml-transform)
+
+You need to build examples according to the [Projects with CRaC support](#projects-with-crac-support) section.
+
+Then run
+```
+host$ docker build -t full-bench -f Dockerfile.full-bench utils
+host$ docker run -it --privileged -v $HOME:$HOME -v $PWD:$PWD -w $PWD full-bench
+cont# JDK=<path/to/jdk> bash ./utils/full-bench.sh collect
+...
+cont# exit
+host$ bash ./utils/full-bench.sh parse
+host$ cp *.data docs
+host$ make -C docs
+```
+Last command regenerates graphs in the `docs`.
+
+---
+</details>
+
+![Startup Time](/images/results/startup.png)
+
+![Spring Boot](/images/results/spring-boot.png)
+
+![Quarkus](/images/results/quarkus.png)
+
+![Micronaut](/images/results/micronaut.png)
+
+![xml-transform](/images/results/xml-transform.png)
+

content/examples/_index.md

@@ -0,0 +1,8 @@
++++
+title = "Example implementations"
+weight = 15
++++
+
+Some example implementations are available on these pages:
+
+{{% children sort="weight" %}}