Skip to content

Commit f2fc85a

Browse files
FDelporteFDelporte
committed
Initial commit
0 parents  commit f2fc85a

File tree

1,093 files changed

+51307
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,093 files changed

+51307
-0
lines changed

‎.github/workflows/hugo.yaml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: github pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
with:
14+
submodules: true # Fetch Hugo themes (true or recursive)
15+
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
16+
17+
- name: Setup Hugo
18+
uses: peaceiris/actions-hugo@v3
19+
with:
20+
hugo-version: 'latest'
21+
extended: true
22+
23+
- name: Build
24+
run: hugo --minify
25+
26+
- name: Deploy
27+
uses: peaceiris/actions-gh-pages@v4
28+
if: github.ref == 'refs/heads/main'
29+
with:
30+
github_token: ${{ secrets.GITHUB_TOKEN }}
31+
publish_dir: ./public

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.idea/
2+
/.hugo_build.lock

‎README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# CRaC Documentation
2+
3+
This repository contains the sources of the CRaC documentation that is provided on [crac.org](http://crac.org/).
4+
5+
## Static Website Generation
6+
7+
* The website is generated with [Hugo](https://gohugo.io/).
8+
* The theme is [Relearn](https://mcshelby.github.io/hugo-theme-relearn/index.html).
9+
* The website is built and published to GitHub Pages with a GitHub Action.
10+
11+
### Run Locally
12+
13+
* Install Hugo, on macOS: `brew install hugo`.
14+
* Run the website with `hugo serve`.
15+
* The website is available on [localhost:1313](http://localhost:1313/).

‎archetypes/default.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
3+
date = {{ .Date }}
4+
draft = true
5+
+++

‎content/_index.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
+++
2+
title = "Coordinated Restore at Checkpoint"
3+
weight = 1
4+
+++
5+
6+
{{% notice style="blue" title="What is CRaC?" icon="java" %}}
7+
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.
8+
{{% /notice %}}
9+
10+
<div style="text-align: center">
11+
12+
{{% button href="/use/implement-crac/" style="blue" icon="fas fa-github" %}}CRaC IN YOUR CODE{{% /button %}}
13+
{{% button href="/use/checkpoint-and-restore/" style="blue" icon="rocket" %}}USING CRaC{{% /button %}}
14+
15+
{{% button href="https://github.com/CRaC/org.crac/tags" style="blue" icon="bookmark" %}}CRaC API 1.4.0 NOW AVAILABLE{{% /button %}}
16+
17+
## Why CRaC?
18+
19+
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.
20+
21+
## USED BY
22+
23+
<div style="display: flex; justify-content: space-between;">
24+
25+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
26+
<img src="/images/logo/spring.png" height="50px" />
27+
<span style="font-weight: bold; font-size: 1.4em;">Spring Boot</span>
28+
<br/><br/>
29+
30+
{{% button href="https://github.com/CRaC/example-spring-boot" style="blue" icon="github" %}}Example project{{% /button %}}
31+
32+
[More info](/frameworks/spring-boot/)
33+
34+
</span>
35+
36+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
37+
<img src="/images/logo/quarkus.svg" height="50px" />
38+
<span style="font-weight: bold; font-size: 1.4em;">Quarkus</span>
39+
<br/><br/>
40+
41+
{{% button href="https://github.com/CRaC/example-quarkus" style="blue" icon="github" %}}Example project{{% /button %}}
42+
43+
[More info](/frameworks/quarkus/)
44+
45+
</span>
46+
47+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
48+
<img src="/images/logo/micronaut.webp" height="50px" />
49+
<span style="font-weight: bold; font-size: 1.4em;">Micronaut</span>
50+
<br/><br/>
51+
52+
{{% button href="https://github.com/CRaC/example-micronaut" style="blue" icon="git" %}}Example project{{% /button %}}
53+
54+
[More info](/frameworks/micronaut/)
55+
56+
</span>
57+
58+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
59+
<img src="/images/logo/aws-lambda.webp" height="50px" />
60+
<span style="font-weight: bold; font-size: 1.4em;">AWS Lambda</span>
61+
<br/><br/>
62+
63+
{{% button href="https://github.com/CRaC/example-lambda" style="blue" icon="github" %}}Example project{{% /button %}}
64+
65+
[More info](/frameworks/aws-lambda/)
66+
67+
</span>
68+
</div>
69+
70+
## Features
71+
72+
<div style="display: flex; justify-content: space-between;">
73+
74+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
75+
<span style="font-weight: bold; font-size: 1.4em;">Super fast startup</span>
76+
<br/><br/>
77+
Startup within milliseconds from a checkpoint.
78+
</span>
79+
80+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
81+
<span style="font-weight: bold; font-size: 1.4em;">Checkpoint creation</span>
82+
<br/><br/>
83+
Generate checkpoints from code or with jcmd.
84+
</span>
85+
86+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
87+
<span style="font-weight: bold; font-size: 1.4em;">Restore from checkpoint</span>
88+
<br/><br/>
89+
Restore on the same machine, or many others from a checkpoint.
90+
91+
</div>
92+
93+
<div style="display: flex; justify-content: space-between;">
94+
95+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
96+
<span style="font-weight: bold; font-size: 1.4em;">Minimal code changes</span>
97+
<br/><br/>
98+
Use frameworks, or implement the CRaC API to assist in the creation and restore of checkpoints
99+
</span>
100+
101+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
102+
<span style="font-weight: bold; font-size: 1.4em;">Framework support</span>
103+
<br/><br/>
104+
Several frameworks (Spring Boot, Quarkus, Micronaut,...) offer CRaC support out-of-the-box.
105+
</span>
106+
107+
<span style="border: solid 1px black; padding: 10px; margin: 10px; flex-grow: 1; text-align: center;">
108+
<span style="font-weight: bold; font-size: 1.4em;">Use it in the Cloud</span>
109+
<br/><br/>
110+
AWS Lambda has CRaC functionality integrated, no code changes needed!
111+
</span>
112+
113+
</div>
114+
115+
</div>

‎content/about/_index.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
+++
2+
title = "About CRaC"
3+
weight = 10
4+
+++
5+
6+
Several frameworks provide CRaC functionality out-of-the-box.
7+
8+
{{% children sort="weight" %}}

‎content/about/about-crac.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
+++
2+
title = "What is Coordinated Restore at Checkpoint?"
3+
weight = 11
4+
+++
5+
6+
Coordinated Restore at Checkpoint (CRaC) is an OpenJDK feature that provides a fast start and immediate performance for Java applications.
7+
8+
A Java application and JVM are started from an image in a warmed-up form.
9+
The image is created from a running Java instance at arbitrary point of time ("checkpoint").
10+
The start from the image ("restore") continues from the point when checkpoint was made.
11+
12+
The restore in general is faster than initialization.
13+
After the restore, Java runtime performance is also on-par with the one at the checkpoint.
14+
So, after proper warm-up before the checkpoint, restored Java instance is able to deliver the best runtime characteristics immediately.
15+
16+
Coordinated Restore undisruptively introduces new before-checkpoint and after-restore phases in Java application lifecycle.
17+
In contrast with uncoordinated checkpoint/restore, coordination allows restored Java applications to behave differently.
18+
For example, it is possible to react on changes in execution environment that happened since checkpoint was done.
19+
20+
CRaC implementation creates the checkpoint only if the whole Java instance state can be stored in the image.
21+
Resources like open files or sockets are cannot, so it is required to release them when checkpoint is made.
22+
CRaC emits notifications for an application to prepare for the checkpoint and return to operating state after restore.
23+
24+
With more Java frameworks and libraries adopting CRaC, applications can benefit with little or no changes in the code.
25+
Moreover, the required amount of changes in the resource management code tends to be small, see examples below.
26+
27+
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.
28+
29+
30+
### CPU Features
31+
32+
When running checkpoint and restore on different computers you may seen an error message during restore
33+
34+
```
35+
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 [...]
36+
```
37+
38+
See [more details about the CPU Features configuration](cpu-features.md).
39+
40+
## Programmer's flow
41+
42+
Programs may need to be adjusted for use with Coordinated Restore at Checkpoint.
43+
44+
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.
45+
46+
Another option is to use an existing framework with CRaC support.
47+
48+
No changes required:
49+
* Micronaut: https://github.com/CRaC/example-micronaut
50+
* Quarkus Hello World: https://github.com/CRaC/example-quarkus
51+
* Spring Boot: https://github.com/CRaC/example-spring-boot
52+
53+
With configuration changes:
54+
* [Quarkus Super Heroes migration](super-heroes.md) shows a walkthrough for making an existing non-trivial Quarkus application CRaC-able.
55+
56+
### API
57+
58+
The CRaC API is not a part of Java SE specification.
59+
We hope that eventually it will be there, until then there are different packages that can be used.
60+
61+
#### `jdk.crac`
62+
63+
* [javadoc](https://crac.github.io/jdk/jdk-crac/api/java.base/jdk/crac/package-summary.html)
64+
65+
This is the API that is implemented in the [CRaC JDK](#JDK).
66+
67+
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.
68+
69+
#### `org.crac`
70+
71+
The package is provided by [org.crac](https://github.com/org-crac/org.crac) compatibility library.
72+
73+
The org.crac is designed to provide smooth CRaC adoption.
74+
Users of the library can build against and use CRaC API on Java runtimes with `jdk.crac`, `javax.crac`, or without any implementation.
75+
* In compile-time, `org.crac` package totally mirrors `jdk.crac` and `javax.crac`.
76+
* In runtime, org.crac uses reflection to detect CRaC implementation.
77+
If the one is available, all requests to `org.crac` are passed to the implementation.
78+
Otherwise, requests are forwarded to a dummy implementation.
79+
80+
The dummy implementation allows an application to run but not to use CRaC:
81+
* resources can be registered for notification,
82+
* checkpoint request fails with an exception.
83+
84+
85+
## Implementation details
86+
87+
Current OpenJDK implementation is based on using the CRIU project to create the image.
88+
89+
[CRIU](https://github.com/CRaC/criu) hosts a few changes made to improve CRaC usability.
90+
91+
You can read more about debugging C/R issues in your application in the [debug guide](./debugging.md).
92+
93+
## Workarounds
94+
95+
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).
96+

‎content/about/jdk-project.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
+++
2+
title = "OpenJDK CRaC Project"
3+
weight = 13
4+
+++
5+
6+
OpenJDK CRaC Project is developed in https://github.com/openjdk/crac.
7+
8+
Latest release can be found in https://crac.github.io/openjdk-builds.
9+
10+
```sh
11+
$ sudo tar zxf <jdk>.tar.gz
12+
```
13+
14+
**NOTE**: The JDK archive should be extracted with `sudo`.
15+
16+
When using CRaC, if you see an "Operation not permitted" error, you may have to update your `criu` permissions with:
17+
18+
```sh
19+
sudo chown root:root $JAVA_HOME/lib/criu
20+
sudo chmod u+s $JAVA_HOME/lib/criu
21+
```
22+

‎content/about/results.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
+++
2+
title = "Startup Improvement Results"
3+
weight = 12
4+
+++
5+
6+
CRaC support was implemented in a few frameworks with the following results.
7+
The source code can be found in the [Projects with CRaC support](#projects-with-crac-support) section.
8+
9+
<details><summary>The environment</summary>
10+
<p>
11+
12+
* laptop with Intel i7-5500U, 16Gb RAM and SSD.
13+
* Linux kernel 5.7.4-arch1-1
14+
* data was collected in container running `ubuntu:18.04` based image
15+
* host operating system: archlinux
16+
17+
[jdk14-crac build](https://github.com/org-crac/jdk/releases/tag/release-jdk-crac)
18+
19+
---
20+
</p>
21+
</details>
22+
23+
<details><summary>How to reproduce</summary>
24+
<p>
25+
26+
To reproduce you need to create a workspace directory and clone along next repositories:
27+
* [utils](https://github.com/org-crac/utils)
28+
* [docs](https://github.com/org-crac/docs) (this repo)
29+
* [example-spring-boot](https://github.com/org-crac/example-spring-boot)
30+
* [example-quarkus](https://github.com/org-crac/example-quarkus)
31+
* [example-micronaut](https://github.com/org-crac/example-micronaut)
32+
* [example-xml-transform](https://github.com/org-crac/example-xml-transform)
33+
34+
You need to build examples according to the [Projects with CRaC support](#projects-with-crac-support) section.
35+
36+
Then run
37+
```
38+
host$ docker build -t full-bench -f Dockerfile.full-bench utils
39+
host$ docker run -it --privileged -v $HOME:$HOME -v $PWD:$PWD -w $PWD full-bench
40+
cont# JDK=<path/to/jdk> bash ./utils/full-bench.sh collect
41+
...
42+
cont# exit
43+
host$ bash ./utils/full-bench.sh parse
44+
host$ cp *.data docs
45+
host$ make -C docs
46+
```
47+
Last command regenerates graphs in the `docs`.
48+
49+
---
50+
</details>
51+
52+
![Startup Time](/images/results/startup.png)
53+
54+
![Spring Boot](/images/results/spring-boot.png)
55+
56+
![Quarkus](/images/results/quarkus.png)
57+
58+
![Micronaut](/images/results/micronaut.png)
59+
60+
![xml-transform](/images/results/xml-transform.png)
61+

‎content/examples/_index.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
+++
2+
title = "Example implementations"
3+
weight = 15
4+
+++
5+
6+
Some example implementations are available on these pages:
7+
8+
{{% children sort="weight" %}}

0 commit comments

Comments
 (0)