Skip to content

Commit 43561ae

Browse files
EmmaChronicleEmmaChronicle
authored
Update README.adoc
updated to adoc format
1 parent 119cb80 commit 43561ae

1 file changed

Lines changed: 51 additions & 42 deletions

File tree

‎README.adoc‎

Lines changed: 51 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,34 @@
1-
Thread Affinity
2-
=============
1+
= Thread Affinity
32

4-
## Version
5-
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.openhft/affinity/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.openhft/affinity)
3+
=== Version
64

7-
## Overview
5+
[#image-maven]
6+
[caption="", link=https://maven-badges.herokuapp.com/maven-central/net.openhft/affinity]
7+
image::https://maven-badges.herokuapp.com/maven-central/net.openhft/affinity/badge.svg[]
8+
9+
=== Overview
810
Lets you bind a thread to a given core, this can improve performance (this library works best on linux).
911

1012
OpenHFT Java Thread Affinity library
1113

12-
See [affinity/src/test/java](https://github.com/OpenHFT/Java-Thread-Affinity/tree/master/affinity/src/test/java)
14+
See https://github.com/OpenHFT/Java-Thread-Affinity/tree/master/affinity/src/test/java[affinity/src/test/java]
1315
for working examples of how to use this library.
1416

15-
## Wold Wide Usage
16-
[Thread Affinity usage Heatmap](http://jrvis.com/red-dwarf/?user=openhft&repo=Java-Thread-Affinity)
17+
==== Wold Wide Usage
18+
http://jrvis.com/red-dwarf/?user=openhft&repo=Java-Thread-Affinity[Thread Affinity usage Heatmap]
1719

18-
## Changes
20+
==== Changes
1921

20-
- V3.1.1 - Upgraded JNA dependency to 4.4.0
21-
- V2.0.1 - Added getThreadId for the process if of the thread.
22+
* V3.1.1 - Upgraded JNA dependency to 4.4.0
23+
* V2.0.1 - Added getThreadId for the process if of the thread.
2224

23-
## Dependencies
25+
=== Dependencies
2426

25-
Java-Thread-Affinity will try to use [JNA](https://github.com/java-native-access/jna)
27+
Java-Thread-Affinity will try to use https://github.com/java-native-access/jna[JNA]
2628
to provide access to native thread-handling functions. JNA should be installed on
2729
your system to get the most from this library.
2830

29-
### JNA version
31+
==== JNA version
3032

3133
Java-Thread-Affinity currently depends on JNA version 4.4.0, which in turn
3234
depends on a version of GLIBC >= 2.14. If your operating system is an old one,
@@ -36,15 +38,15 @@ invoke native functions.
3638
To work around this problem, fork the repository, and override the `<version>` tag
3739
for the artifacts `jna` and `jna-platform` in the project's `pom` file.
3840

39-
### Installing JNA on Ubuntu
41+
==== Installing JNA on Ubuntu
4042

4143
sudo apt-get install libjna-java
4244

43-
### Installing JNA on CentOS
45+
==== Installing JNA on CentOS
4446

4547
sudo yum install jna
4648

47-
## How does CPU allocation work?
49+
=== How does CPU allocation work?
4850
The library will read your `/proc/cpuinfo` if you have one or provide one and it will determine your CPU layout. If you don't have one it will assume every CPU is on one CPU socket.
4951

5052
The library looks for isolated CPUs determined by looking at the CPUs you are not running on by default.
@@ -55,15 +57,15 @@ To control which CPUs a process can use, add -Daffinity.reserved={cpu-mask-in-he
5557

5658
Note: the CPU 0 is reserved for the Operating System, it has to run somewhere.
5759

58-
## References
60+
=== References
5961

6062
https://github.com/peter-lawrey/Java-Thread-Affinity/wiki/Getting-started
6163

6264
https://github.com/peter-lawrey/Java-Thread-Affinity/wiki/How-it-works
6365

6466
http://vanillajava.blogspot.co.uk/2013/07/micro-jitter-busy-waiting-and-binding.html
6567

66-
## isolcpus
68+
=== isolcpus
6769

6870
Java-Thread-Affinity requires that you first isolate some CPU's.
6971

@@ -73,36 +75,41 @@ To isolate the 1st and 3rd CPU cores (CPU numbers start from 0) on your system,
7375

7476
isolcpus=1,3
7577

76-
## Acquiring a CPU lock for a thread
78+
==== Acquiring a CPU lock for a thread
7779
You can acquire a lock for a CPU in the following matter
7880

7981
In Java 6
80-
82+
[source, java]
83+
----
8184
AffinityLock al = AffinityLock.acquireLock();
8285
try {
8386
// do some work locked to a CPU.
8487
} finally {
8588
al.release();
8689
}
90+
----
8791

8892
In Java 7 or 8
89-
93+
[source, java]
94+
----
9095
try (AffinityLock al = AffinityLock.acquireLock()) {
9196
// do some work while locked to a CPU.
9297
}
93-
98+
----
9499
You have further options such as
95100

96-
## Acquiring a CORE lock for a thread
101+
=== Acquiring a CORE lock for a thread
97102
You can reserve a whole core. If you have hyper-threading enabled, this will use one CPU and leave it's twin CPU unused.
98-
103+
[source, java]
104+
----
99105
try (AffinityLock al = AffinityLock.acquireCore()) {
100106
// do some work while locked to a CPU.
101107
}
102-
103-
## Controlling layout
108+
----
109+
=== Controlling layout
104110
You can chose a layout relative to an existing lock.
105-
111+
[source, java]
112+
----
106113
try (final AffinityLock al = AffinityLock.acquireLock()) {
107114
System.out.println("Main locked");
108115
Thread t = new Thread(new Runnable() {
@@ -116,20 +123,20 @@ You can chose a layout relative to an existing lock.
116123
});
117124
t.start();
118125
}
119-
126+
----
120127
In this example, the library will prefer a free CPU on the same Socket as the first thread, otherwise it will pick any free CPU.
121128

122-
## Getting the thread id.
129+
=== Getting the thread id.
123130
You can get the current thread id using
124131

125132
int threadId = AffinitySupport.getThreadId();
126133

127-
## Determining which CPU you are running on.
134+
=== Determining which CPU you are running on.
128135
You can get the current CPU being used by
129136

130137
int cpuId = AffinitySupport.getCpu();
131138

132-
## Controlling the affinity more directly.
139+
=== Controlling the affinity more directly.
133140
The affinity of the process on start up is
134141

135142
long baseAffinity = AffinityLock.BASE_AFFINITY;
@@ -143,12 +150,13 @@ If you want to get/set the affinity directly you can do
143150
long currentAffinity = AffinitySupport.getAffinity();
144151
AffinitySupport.setAffinity(1L << 5); // lock to CPU 5.
145152

146-
## Debugging affinity state
153+
=== Debugging affinity state
147154

148155
For a detailed of view of the current affinity state (as seen by the library),
149156
execute the following script on Linux systems:
150157

151-
```
158+
[source]
159+
----
152160
# change to the affinity lock-file directory (defaults to system property java.io.tmpdir)
153161
$ cd /tmp
154162
@@ -163,27 +171,28 @@ $ for i in "$(ls cpu-*)";
163171
pid 14584's current affinity list: 3
164172
/opt/jdk1.8.0_141/bin/java ...
165173
166-
```
174+
----
167175

168-
# Support Material
176+
== Support Material
169177

170-
[Java Thread Affinity support group](https://groups.google.com/forum/?hl=en-GB#!forum/java-thread-affinity)
178+
https://groups.google.com/forum/?hl=en-GB#!forum/java-thread-affinity[Java Thread Affinity support group]
171179

172180
For an article on how much difference affinity can make and how to use it http://vanillajava.blogspot.com/2013/07/micro-jitter-busy-waiting-and-binding.html
173181

174-
# Questions and Answers
182+
== Questions and Answers
175183

176-
## Question
184+
=== Question
177185
I am currently working on a project related to deadlock detection in multithreaded programs in java. We are trying to run threads on different processors and thus came across your github posts regarding the same. https://github.com/peter-lawrey/Java-Thread-Affinity/wiki/Getting-started
178186
Being a beginner, I have little knowledge and thus need your assistance. We need to know how to run threads on specified cpu number and then switch threads when one is waiting.
179187

180-
## Answer
188+
=== Answer
181189

182190
Use :
183191

184-
``` java
192+
[source, java]
193+
----
185194
AffinityLock.setAffinity (1L << n);
186-
```
195+
----
187196

188197
where n is the cpu you want to run the thread on.
189198

0 commit comments

Comments
 (0)