• Stars
    star
    810
  • Rank 56,306 (Top 2 %)
  • Language
    Java
  • License
    GNU General Publi...
  • Created about 4 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

https://openjdk.org/projects/code-tools/jol

Java Object Layout (JOL)

JOL (Java Object Layout) is the tiny toolbox to analyze object layout in JVMs. These tools are using Unsafe, JVMTI, and Serviceability Agent (SA) heavily to decode the actual object layout, footprint, and references. This makes JOL much more accurate than other tools relying on heap dumps, specification assumptions, etc.

Usage

JOL Samples

You can have a brief tour of JOL capabilities by looking through the JOL Samples. You can run them from the IDE, or using the JAR file:

$ java -cp jol-samples/target/jol-samples.jar org.openjdk.jol.samples.JOLSample_01_Basic

Use as Library Dependency

Maven Central contains the latest releases. You can use them right away with this Maven dependency:

<dependency>
    <groupId>org.openjdk.jol</groupId>
    <artifactId>jol-core</artifactId>
    <version>put-the-version-here</version>
</dependency>

JOL module would try to self-attach as Java Agent, if possible. If you are using JOL as the library, it is recommended to add Premain-Class and Launcher-Agent attributes to the final JAR manifest.

Use as Command Line Tool

Build produces the self-contained executable JAR in jol-cli/target/jol-cli.jar. Published Maven artifacts also include the executable JAR that one can download and start using right away. The JAR is published both at jol-cli-$version-full.jar at Maven Central or here.

List the supported commands with -h:

$ java -jar jol-cli.jar -h
Usage: jol-cli.jar <mode> [optional arguments]*

Available modes:
         estimates: Simulate the class layout in different VM modes.
         externals: Show the object externals: the objects reachable from a given instance.
         footprint: Estimate the footprint of all objects reachable from a given instance
     heapdumpstats: Consume the heap dump and print the most frequent instances.
         internals: Show the object internals: field layout and default contents, object header
            shapes: Dump the object shapes present in JAR files or heap dumps.
   string-compress: Consume the heap dumps and figures out the savings attainable with compressed strings.

A brief tour of commands follows.

"internals"

This dives into Object layout: field layout within the object, header information, field values, alignment/padding losses.

$ java -jar jol-cli.jar internals java.util.HashMap
# Running 64-bit HotSpot VM.
# Using compressed oop with 3-bit shift.
# Using compressed klass with 3-bit shift.
# Objects are 8 bytes aligned.
# Field sizes by type: 4, 1, 1, 2, 2, 4, 4, 8, 8 [bytes]
# Array element sizes: 4, 1, 1, 2, 2, 4, 4, 8, 8 [bytes]

Instantiated the sample instance via default constructor.

java.util.HashMap object internals:
OFF  SZ                       TYPE DESCRIPTION               VALUE
  0   8                            (object header: mark)     0x0000000000000005 (biasable; age: 0)
  8   4                            (object header: class)    0x00019828
 12   4              java.util.Set AbstractMap.keySet        null
 16   4       java.util.Collection AbstractMap.values        null
 20   4                        int HashMap.size              0
 24   4                        int HashMap.modCount          0
 28   4                        int HashMap.threshold         0
 32   4                      float HashMap.loadFactor        0.75
 36   4   java.util.HashMap.Node[] HashMap.table             null
 40   4              java.util.Set HashMap.entrySet          null
 44   4                            (object alignment gap)
Instance size: 48 bytes
Space losses: 0 bytes internal + 4 bytes external = 4 bytes total

"externals"

This dives into the Object graphs layout: list objects reachable from the instance, their addresses, paths through the reachability graph, etc (is more convenient with API though).

$ java -jar jol-cli.jar externals java.lang.String
# Running 64-bit HotSpot VM.
# Using compressed oop with 3-bit shift.
# Using compressed klass with 3-bit shift.
# Objects are 8 bytes aligned.
# Field sizes by type: 4, 1, 1, 2, 2, 4, 4, 8, 8 [bytes]
# Array element sizes: 4, 1, 1, 2, 2, 4, 4, 8, 8 [bytes]

Instantiated the sample instance via default constructor.

java.lang.String@64cee07d object externals:
     ADDRESS       SIZE TYPE             PATH                           VALUE
   58010a600         16 [C               .value                         []
   58010a610    8923824 (something else) (somewhere else)               (something else)
   58098d0c0         24 java.lang.String                                (object)

Addresses are stable after 1 tries.

"footprint"

This gets the object footprint estimate, similar to the object externals, but tabulated.

$ java -jar jol-cli/target/jol-cli.jar footprint java.lang.Thread
# Running 64-bit HotSpot VM.
# Using compressed oop with 3-bit shift.
# Using compressed klass with 3-bit shift.
# Objects are 8 bytes aligned.
# Field sizes by type: 4, 1, 1, 2, 2, 4, 4, 8, 8 [bytes]
# Array element sizes: 4, 1, 1, 2, 2, 4, 4, 8, 8 [bytes]

Instantiated the sample instance via default constructor.

java.lang.Thread@64cee07d footprint:
COUNT       AVG       SUM   DESCRIPTION
   13        84      1104   [B
  496        67     33400   [C
  139        23      3272   [Ljava.lang.Class;
   17        89      1520   [Ljava.lang.Object;
 ...
    1        24        24   sun.reflect.generics.tree.ClassSignature
    3        16        48   sun.reflect.generics.tree.ClassTypeSignature
    2        24        48   sun.reflect.generics.tree.FormalTypeParameter
    3        24        72   sun.reflect.generics.tree.SimpleClassTypeSignature
 2849              200416   (total)

Reporting Bugs

You may find unresolved bugs and feature request in JDK Bug System Please submit the new bug there:

  • Project: CODETOOLS
  • Component: tools
  • Sub-component: jol

If you don't have the access to JDK Bug System, submit the bug report at Issues here, and wait for maintainers to pick that up.

Development

JOL project accepts pull requests, like other OpenJDK projects. If you have never contributed to OpenJDK before, then bots would require you to sign OCA first. Normally, you don't need to post patches anywhere else, or post to mailing lists, etc. If you do want to have a wider discussion about JOL, please refer to jol-dev.

Compile and run tests:

$ mvn clean verify

Tests would normally run in many JVM configurations. If you are contributing the code, please try to run the build on multiple JDK releases, most importantly 8u and 11u. GitHub workflow "JOL Pre-Integration Tests" should pass with your changes.

Related projects

More Repositories

1

jdk

JDK main-line development https://openjdk.org/projects/jdk
Java
17,577
star
2

jfx

JavaFX mainline development
C++
2,700
star
3

loom

https://openjdk.org/projects/loom
Java
1,873
star
4

jmh

https://openjdk.org/projects/code-tools/jmh
Java
1,857
star
5

jmc

Repository for OpenJDK Mission Control, a production time profiling and diagnostics tools suite. https://openjdk.org/projects/jmc
Java
836
star
6

valhalla

https://openjdk.org/projects/valhalla
Java
538
star
7

nashorn

https://openjdk.org/projects/nashorn
Java
399
star
8

jcstress

https://openjdk.org/projects/code-tools/jcstress
Java
368
star
9

panama-foreign

https://openjdk.org/projects/panama
Java
291
star
10

jextract

https://openjdk.org/projects/code-tools
Java
237
star
11

skara

https://openjdk.org/projects/skara
Java
203
star
12

jdk8u

https://wiki.openjdk.org/display/jdk8u
Java
187
star
13

wakefield

https://openjdk.org/projects/wakefield
Java
186
star
14

amber

https://openjdk.org/projects/amber
Java
181
star
15

crac

https://openjdk.org/projects/crac
Java
175
star
16

jdk17

https://openjdk.org/projects/jdk/17 released 2021-09-14
Java
164
star
17

zgc

The Z Garbage Collector https://wiki.openjdk.org/display/zgc
Java
164
star
18

amber-docs

https://openjdk.org/projects/amber
HTML
144
star
19

mobile

https://openjdk.org/projects/mobile
Java
134
star
20

jdk11u

https://openjdk.org/projects/jdk-updates
Java
130
star
21

shenandoah

https://openjdk.org/projects/shenandoah
Java
117
star
22

leyden

https://openjdk.org/projects/leyden
Java
97
star
23

panama-vector

https://openjdk.org/projects/panama
Java
82
star
24

shenandoah-visualizer

https://openjdk.org/projects/shenandoah
Java
78
star
25

jdk17u

https://wiki.openjdk.org/display/JDKUpdates/JDK+17u
Java
76
star
26

aarch64-port

Port: AArch64 Project
Java
71
star
27

babylon

https://openjdk.org/projects/babylon
Java
69
star
28

asmtools

https://wiki.openjdk.org/display/CodeTools/asmtools
Java
66
star
29

jdk21

https://openjdk.org/projects/jdk/21 released 2023-09-19
Java
65
star
30

valhalla-docs

https://openjdk.org/projects/valhalla
CSS
59
star
31

jdk-sandbox

JDK Committers Sandbox
Java
59
star
32

guide

OpenJDK Developers' Guide https://openjdk.org/guide
Makefile
58
star
33

jdk16

https://openjdk.org/projects/jdk/16 released 2021-03-16
Java
57
star
34

jtreg

https://openjdk.org/projects/code-tools/jtreg
Java
56
star
35

jdk11u-dev

https://openjdk.org/projects/jdk-updates
Java
54
star
36

lilliput

https://openjdk.org/projects/lilliput
Java
50
star
37

riscv-port

https://openjdk.org/projects/riscv-port
Java
46
star
38

jdk8

https://openjdk.org/projects/jdk8 released 2014-03-18
Java
40
star
39

jdk8u-dev

https://wiki.openjdk.org/display/jdk8u
Java
40
star
40

jdk15

https://openjdk.org/projects/jdk/15 released 2020-09-15
Java
39
star
41

jdk19

https://openjdk.org/projects/jdk/19 released 2022-09-20
Java
39
star
42

jmh-jdk-microbenchmarks

https://openjdk.org/projects/code-tools/jmh-jdk-microbenchmarks
Java
38
star
43

jdk17u-dev

https://openjdk.org/projects/jdk-updates
Java
32
star
44

jdk13

https://openjdk.org/projects/jdk/13 released 2019-09-17
Java
32
star
45

jdk21u

https://openjdk.org/projects/jdk-updates
Java
30
star
46

jdk16u

https://openjdk.org/projects/jdk-updates last released 2021-07-20
Java
26
star
47

lanai

https://openjdk.org/projects/lanai
Java
26
star
48

tsan

https://openjdk.org/projects/tsan
Java
25
star
49

portola

https://openjdk.org/projects/portola
Java
24
star
50

jdk18

https://openjdk.org/projects/jdk/18 released 2022-03-22
Java
23
star
51

duke

https://openjdk.org/projects/duke
Mathematica
21
star
52

jdk19u

https://openjdk.org/projects/jdk-updates last released 2023-01-17
Java
20
star
53

jdk11

https://openjdk.org/projects/jdk/11 released 2018-09-25
20
star
54

jdk20

https://openjdk.org/projects/jdk/20 released 2023-03-21
Java
20
star
55

jdk13u-dev

https://openjdk.org/projects/jdk-updates development (identical to jdk13u)
Java
17
star
56

jcov

https://wiki.openjdk.org/display/CodeTools/jcov
Java
17
star
57

jdk14u

https://openjdk.org/projects/jdk-updates last released 2020-07-14
Java
16
star
58

jdk12u

https://openjdk.org/projects/jdk-updates last released 2019-07-16
Java
16
star
59

metropolis

https://openjdk.org/projects/metropolis
Java
16
star
60

jdk20u

https://openjdk.org/projects/jdk-updates last released 2023-07-18
Java
15
star
61

jdk14

https://openjdk.org/projects/jdk/14 released 2020-03-17
Java
15
star
62

galahad

https://openjdk.org/projects/galahad
Java
15
star
63

jfx-sandbox

OpenJFX Committers Sandbox
C++
14
star
64

jdk6

https://openjdk.org/projects/jdk6
Java
14
star
65

jtharness

https://wiki.openjdk.org/display/CodeTools/JT+Harness
Java
13
star
66

jdk7u

https://wiki.openjdk.org/display/jdk7u last released 2022-07-19
Java
12
star
67

jfx11u

JavaFX 11 updates development
C++
12
star
68

jmc7

https://openjdk.org/projects/jmc
Java
12
star
69

jdk15u

https://wiki.openjdk.org/display/JDKUpdates/JDK+15u last released 2023-01-18
Java
11
star
70

jemmy-v2

UI test automation library - v2
Java
11
star
71

jfx20u

JavaFX 20.x: last released 2023-07-18
C++
10
star
72

jdk7

https://openjdk.org/projects/jdk7 released 2011-07-28
Java
10
star
73

jdk12

https://openjdk.org/projects/jdk/12 released 2019-03-19
8
star
74

webrevs

Automatically generated JSON files for webrevs
8
star
75

jdk15u-dev

https://openjdk.org/projects/jdk-updates development (identical to jdk15u)
Java
8
star
76

jfx21u

JavaFX 21 updates development
C++
7
star
77

jdk13u

https://wiki.openjdk.org/display/JDKUpdates/JDK+13u last released 2023-01-18
Java
7
star
78

client

JDK 16 era Client Libraries development
Java
7
star
79

jfx17u

JavaFX 17 updates development
C++
6
star
80

jdk18u

https://openjdk.org/projects/jdk-updates last released 2022-08-18
Java
6
star
81

playground

Repository for experimenting. May be synced and/or reset at any time without notice.
Java
6
star
82

lilliput-jdk17u

https://openjdk.org/projects/lilliput
Java
6
star
83

cr

https://openjdk.org/projects/skara
HTML
6
star
84

jdk22

https://openjdk.org/projects/jdk/22
Java
6
star
85

riscv-port-jdk17u

https://openjdk.org/projects/riscv-port
Java
6
star
86

sigtest

https://wiki.openjdk.org/display/CodeTools/sigtest
Java
5
star
87

shenandoah-jdk8u

https://openjdk.org/projects/shenandoah
Java
5
star
88

friday-stats

https://openjdk.org/projects/code-tools/friday-stats
Java
4
star
89

jdk9

https://openjdk.org/projects/jdk9 released 2017-09-21
Java
4
star
90

aarch32-port-jdk8u

https://openjdk.org/projects/aarch32-port
Java
4
star
91

jdk11u-ri

JSR 384 Reference Implementation (Java SE 11) [not for production use]
Java
4
star
92

jdk9u

https://openjdk.org/projects/jdk-updates last released 2018-01-16
Java
3
star
93

jfx12

JavaFX 12.x : last released 2019-07-19
C++
3
star
94

jfx13

JavaFX 13.x : last released 2020-01-15
C++
3
star
95

jmc-graphics

https://openjdk.org/projects/jmc
3
star
96

jdk10u

https://openjdk.org/projects/jdk-updates last released 2018-07-17
3
star
97

jemmy-v3

UI test automation library - v3
Java
2
star
98

webrev

https://openjdk.org/projects/code-tools/webrev
Shell
2
star
99

riscv-port-jdk11u

https://openjdk.org/projects/riscv-port
Java
2
star
100

lilliput-jdk21u

https://openjdk.org/projects/lilliput
Java
2
star