1Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved.
2DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
4This code is free software; you can redistribute it and/or modify it
5under the terms of the GNU General Public License version 2 only, as
6published by the Free Software Foundation.
7
8This code is distributed in the hope that it will be useful, but WITHOUT
9ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
11version 2 for more details (a copy is included in the LICENSE file that
12accompanied this code).
13
14You should have received a copy of the GNU General Public License version
152 along with this work; if not, write to the Free Software Foundation,
16Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
18Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19or visit www.oracle.com if you need additional information or have any
20questions.
21
22DESCRIPTION
23
24    This is a lock coarsening test. There are 2 threads, trying to acquire a shared
25    resource. The 1st thread has a number of adjacent lock that are subject to lock
26    coarsening:
27
28    ...
29
30    synchronized( lock )
31    {
32        lock.foo();
33    }
34
35    // (*)
36
37    synchronized( lock )
38    {
39        lock.foo();
40    }
41
42    ...
43
44
45    The test is written in such a way, that thread 2 will acquire the lock, if and
46    only if thread 1 is somewhere at point (*). Therefore, the fact that lock
47    coarsening occurred is described by the condition (numAcquiredLocks != 0).
48
49IMPLEMENTATION
50    The test has one parameter, -eliminateLocks, that tells whether the JVM option
51    -XX:+EliminateLocks has been specified, so running the test without
52    -eliminateLocks checks that lock coarsening didn't occur, and running it with
53    this option check that lock coarsening occurred.
54
55    Some hacks have been made to force JIT compile the method doit() (see comments in
56    the source).
57
58FAILURE ANALYSIS
59    If test fails try to run it with -XX:+PrintOptoAssembly and -XX:+LogCompilation
60    to understand if this is a test or product bug.
61
62    If compiled code of Thread_1::doit method have lot of locks that surround each
63    lock.foo() then coarsening did not happen and this is a product bug.
64
65    If lock coarsening occurs but not triggered by test then it's a test bug
66    that should be investigated. One of such problems could be caused if method doit()
67    was not compiled due to insufficient warm-up iterations. Also there may be a product bug
68    in compilation.
69