-
Notifications
You must be signed in to change notification settings - Fork 12
/
README.txt
140 lines (99 loc) · 5.01 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
--------------------
ABOUT MLOCKALL AGENT
--------------------
mlockall-agent.jar is a Java Agent that can be used in conjunction with any
java application to cause the virtual memory used by the application to be
"locked" in memory -- preventing it from being swapped to disk.
In an ideal world, any performance critical java application would be run
on dedicated hardware with swap disabled -- but people don't always get
to run their software in an ideal world. So this agent fills in the gaps.
Background about the creation of this agent can be found here...
http://searchhub.org/2013/05/21/mlockall-for-all/
------------
REQUIREMENTS
------------
Building the code requires Java 5, Apache Ant, and a jna.jar 3.2.7 or newer
https://ant.apache.org/
https://github.com/twall/jna
Running the agent requires jna.jar 3.2.7 or newer
--------------------
USING MLOCKALL AGENT
--------------------
To run a java application with this agent enabled:
0) Ensure that your system supports mlock and that the effective user of
your java process has a sufficient ulimit for "max locked memory"
(ie: "ulimit -l")
1) Ensure that you configure the min heap size = the max heap size
3) Ensure that the "jna.jar" is either in the same directory as the
mlockall-agent.jar, or is at the same path used when mlockall-agent.jar,
was assembled (see below)
2) Specify the path to the mlockall-agent.jar using the "-javaagent"
command line switch
Example...
$ ls -1 lib
mlockall-agent.jar
jna.jar
$ java -Xms1024m -Xmx1024m -javaagent:lib/mlockall-agent.jar -jar yourapp.jar
By default, the agent will cause the process to fail immediately if mlockall
can not be used for any reason. An "optional" argument can be added to the
agent to specify that you would like it to try to run, but not fail if there
is any problem. This may be useful for developing cross platform start
scripts where you would like a "best attempt" at locking the memory, but can
live w/o it if there is a problem...
$ java -Xms1024m -Xmx1024m -javaagent:lib/mlockall-agent.jar=optional -jar yourapp.jar
The mlockall-agent.jar can also be run explicitly to provide a simple
demo/test mode of whether mlockall() works on your system...
$ less src/MLockAgent.java
$ java -jar build/jar/mlockall-agent.jar
Demo mode of mlockall...
Demo mode of mlockall failed
Exception in thread "main" java.lang.IllegalStateException: Unable to lock JVM memory, error num: 12
at MLockAgent.agent(MLockAgent.java:134)
at MLockAgent.main(MLockAgent.java:70)
$ ulimit -l unlimited
$ java -jar build/jar/mlockall-agent.jar
Demo mode of mlockall...
mlockall finished, sleeping so you can observe process info
^C
-----------------------
BUILDING AND ASSEMBLING
-----------------------
Apache Ant is used to compile the code and assemble the agent jar file.
Use "ant -p" to see the list of build options.
At the present time it is necessary for you to explicitly point the ant build
system to a copy of the JNA jar (using an ant build property) when compiling
the code, and when assembling the jar file. Examples...
# specify the path on the command line
$ ant -Djna.jar.path=/usr/share/java/jna-3.2.7.jar compile jar
# specify the path in a file that can be reused
$ echo "jna.jar.path=/usr/share/java/jna-3.2.7.jar" > build.properties
$ ant clean compile
$ ant jar
Because of how Java Agents are loaded by the JVM, the value of the
"jna.jar.path" used when running "ant jar" will be included in the jar
manifest information as part of the "Boot-Class-Path" for the agent.
At run time, the JVM will look for the JNA jar using:
* "jna.jar" in the same directory as mlockall-agent.jar
* The name of the jar file specified using jna.jar.path in the same
directory as mlockall-agent.jar
* The full path of the jar file specif-ed using jna.jar.path
---
FAQ
---
### Is this agent a good substitute for running with swap disabled?
No, mlockall-agent.jar is not a good substitute for running with swap disabled.
If you have the resources to run your important java processes on dedicated
hardware with swap disabled that is recommended instead of using this agent --
but not everyone has that luxury, and this agent is for you.
### /proc/<pid>/status suggests that not all my heap is locked in memory?
For this agent to run effectively, you must configure your JVM with an initial
min heap size equivalent to your max heap size, otherwise it will allocate
additional memory (to grow the heap) after the agent has run mlockall() and
that new portion of the heap will not be locked into RAM.
### Why does the agent only lock memory at the start of the process?
See the comments in the code related to the MCL_CURRENT constant
### What about mmap'ed data?
See the comments in the code related to the MCL_CURRENT constant
### I'm getting an error even though I set "ulimit -l" bigger then the heap?
The heap is not the only memory in use by your java process, you need to
ensure the ulimit is big enough for all of the memory used by your java process.