JMM测试利器-JCStress学习笔记

<dependency>
 <groupId>org.openjdk.jcstress</groupId>
    <artifactId>jcstress-samples</artifactId>
    <version>0.3</version>
 </dependency>

/*
    This is our first concurrency test. It is deliberately simplistic to show
    testing approaches, introduce JCStress APIs, etc.
 这是我们第一个并发测试，这个测试被刻意的做的很简单,以便展示测试方法、介绍JCStress API等方法。
    Suppose we want to see if the field increment is atomic. 
    我们想看下字段的递增是否是原子性的.
    We can make test with two actors, both actors incrementing the field and recording what value they observed into the result     object. 
    我们可以用两个actor进行测试，两个actor都对字段进行自增，并将观察到的值记录到result对象里面
    As JCStress runs, it will invoke these methods on the objects holding the field once per each actor and instance, and record     what results are coming from there.
    当JCStress运行时，她会对每个"actor"和实例进行一次方法调用，并记录调用的结果。
    Done enough times, we will get the history of observed results, and that
    would tell us something about the concurrent behavior. For example, running
    this test would yield:
    进行充足的测试之后, 我们将会得到观察结果的历史，将会告诉我们并发行为发生了什么,运行这些测试将产生:
      [OK] o.o.j.t.JCStressSample_01_Simple
      (JVM args: [-server])  请求虚拟机以server方式运行
      观察状态           发生的情况     期待           解释    
      Observed state   Occurrences   Expectation  Interpretation
                    // 两个线程得出了相同的值: 原子性测试失败  
                1, 1    54,734,140    ACCEPTABLE  Both threads came up with the same value: atomicity failure.
                          // actor1 先新增  后actor2新增
                1, 2    47,037,891    ACCEPTABLE  actor1 incremented, then actor2.
                          // actor2 先增加, actor1后增加  
                2, 1    53,204,629    ACCEPTABLE  actor2 incremented, then actor1.
      如何运行JCStress测试,            
     How to run this test:
       $ java -jar jcstress-samples/target/jcstress.jar -t JCStress_APISample_01_Simple
 */
 标记这个类是需要JCStress测试的类
// Mark the class as JCStress test.
@JCStressTest
// These are the test outcomes.
@Outcome(id = "1, 1", expect = Expect.ACCEPTABLE_INTERESTING, desc = "Both actors came up with the same value: atomicity failure.")
@Outcome(id = "1, 2", expect = Expect.ACCEPTABLE, desc = "actor1 incremented, then actor2.")
@Outcome(id = "2, 1", expect = Expect.ACCEPTABLE, desc = "actor2 incremented, then actor1.")
// 状态对象     
// This is a state object
@State
public class APISample_01_Simple {
    
    int v;
    
    @Actor
    public void actor1(II_Result r) {
        // 将结果actor1的行为产生的记录进r1
        // record result from actor1 to field r1 
        r.r1 = ++v; 
    }
    
    @Actor
    public void actor2(II_Result r) {
        //将actor2的结果记录进r2
        // record result from actor2 to field r2
        r.r2 = ++v; 
    }
}

class Dog {
  private String name = "旺财";
  // 这种声明 我是头一次见  
  {name = "小小狗"}  
}

//省略II_Result的其他方法和成员变量
@Result
public class II_Result implements Serializable {
    public String toString() {
        return "" + r1 + ", " + r2;
    }
}
//省略III_Result的其他方法和成员变量
@Result
public class IIII_Result implements Serializable {
    public String toString() {
        return "" + r1 + ", " + r2 + ", " + r3 + ", " + r4;
    }
}

v = v + 1;

v = v; 
v = v + 1;

for(int v = 0 ; v < 10 ; v++){}

https://github.com/openjdk/jcstress.git

mvn clean install -DskipTests -T 1C

java -jar jcstress-samples/target/jcstress.jar -t API_01_Simple

/*
    Another flavor of the same test as APISample_01_Simple is using arbiters.
    另一个和APISample_01_Simple一样味道的测试是使用仲裁者。
    
    Arbiters run after both actors, and therefore can observe the final result. 
    Arbiters方法在actor方法运行之后执行,因此可以观察到最后的结果。
 This allows to observe the permanent atomicity failure after both actors  finished.
 在actor方法执行之后,Arbiters方法将会观察到原子性失败的结果 
    How to run this test:
       $ java -jar jcstress-samples/target/jcstress.jar -t API_02_Arbiters
        ...
      RESULT         SAMPLES     FREQ       EXPECT  DESCRIPTION
           1     888,569,404    6.37%  Interesting  One update lost: atomicity failure.
           2  13,057,720,260   93.63%   Acceptable  Actors updated independently.
 */
@JCStressTest
// These are the test outcomes.
@Outcome(id = "1", expect = ACCEPTABLE_INTERESTING, desc = "One update lost: atomicity failure.")
@Outcome(id = "2", expect = ACCEPTABLE,             desc = "Actors updated independently.")
@State
public class API_02_Arbiters {
    int v;
    @Actor
    public void actor1() {
        v++;
    }
    @Actor
    public void actor2() {
        v++;
    }
    @Arbiter
    public void arbiter(I_Result r) {
        r.r1 = v;
    }
}

/*
    Some concurrency tests are not following the "run continously" pattern.
    一些并发测试可能并不适用"持续运行"模式。
    One of interesting test groups is that asserts if the code had terminated after a signal.
    一个有趣的测试是确定代码是否在接收到信号之后终止
    Here, we use a single @Actor that busy-waits on a field, and a @Signal that
    sets that field.
    在下面的例子中，我们使用@Actor来让一个线程在一个字段上忙等，然后用@Signal方法去设置这个字段。
    JCStress would start actor, and then deliver the signal.
    JCStress会首先启动actor，然后启动signal.
    If it exits in reasonable time, it will record "TERMINATED" result, otherwise
    record "STALE".
    如果在一定的时间退出，它将会记录"TERMINATED",否则将会记录state。
    How to run this test:
       $ java -jar jcstress-samples/target/jcstress.jar -t API_03_Termination
        ...
          RESULT  SAMPLES     FREQ       EXPECT  DESCRIPTION
           STALE        1   <0.01%  Interesting  Test hung up.
      TERMINATED   13,168   99.99%   Acceptable  Gracefully finished.
      Messages:
        Have stale threads, forcing VM to exit for proper cleanup.
 */
@JCStressTest(Mode.Termination)
@Outcome(id = "TERMINATED", expect = ACCEPTABLE,             desc = "Gracefully finished.")
@Outcome(id = "STALE",      expect = ACCEPTABLE_INTERESTING, desc = "Test hung up.")
@State
public class API_03_Termination {
    @Actor
    public void actor1() throws InterruptedException {
        synchronized (this) {
            wait();
        }
    }
    @Signal
    public void signal() {
        synchronized (this) {
            notify();
        }
    }
}

/**
 * {@link Signal} is useful for delivering a termination signal to {@link Actor}  in {@link Mode#Termination} tests.
 * Signal 被用于 在中断测试中发送中断信号给Actor。
 *  It will run after {@link Actor} in question  started executing.
 *  它将会在相应的Actor运行之后开始执行。
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Signal {
}

/*
It is sometimes convenient to put the tests in the same source file for better comparison. JCStress allows to nest tests like this:
有时候将一些测试放入一个源文件可以更好的比较，JCStress允许将下面一样嵌套
    How to run this test:
       $ java -jar jcstress-samples/target/jcstress.jar -t API_04_Nesting
        ...
        .......... [OK] org.openjdk.jcstress.samples.api.APISample_04_Nesting.PlainTest
          RESULT      SAMPLES    FREQ       EXPECT  DESCRIPTION
            1, 1   21,965,585    4.5%  Interesting  Both actors came up with the same value: atomicity failure.
            1, 2  229,978,309   47.5%   Acceptable  actor1 incremented, then actor2.
            2, 1  232,647,044   48.0%   Acceptable  actor2 incremented, then actor1.
        .......... [OK] org.openjdk.jcstress.samples.api.APISample_04_Nesting.VolatileTest
          RESULT      SAMPLES    FREQ       EXPECT  DESCRIPTION
            1, 1    4,612,990    1.4%  Interesting  Both actors came up with the same value: atomicity failure.
            1, 2   95,520,678   28.4%   Acceptable  actor1 incremented, then actor2.
            2, 1  236,498,350   70.3%   Acceptable  actor2 incremented, then actor1.
 */
public class API_04_Nesting {
    @JCStressTest
    @Outcome(id = "1, 1", expect = ACCEPTABLE_INTERESTING, desc = "Both actors came up with the same value: atomicity failure.")
    @Outcome(id = "1, 2", expect = ACCEPTABLE,             desc = "actor1 incremented, then actor2.")
    @Outcome(id = "2, 1", expect = ACCEPTABLE,             desc = "actor2 incremented, then actor1.")
    @State
    public static class PlainTest {
        int v;
        @Actor
        public void actor1(II_Result r) {
            r.r1 = ++v;
        }
        @Actor
        public void actor2(II_Result r) {
            r.r2 = ++v;
        }
    }
    @JCStressTest
    @Outcome(id = "1, 1", expect = ACCEPTABLE_INTERESTING, desc = "Both actors came up with the same value: atomicity failure.")
    @Outcome(id = "1, 2", expect = ACCEPTABLE,             desc = "actor1 incremented, then actor2.")
    @Outcome(id = "2, 1", expect = ACCEPTABLE,             desc = "actor2 incremented, then actor1.")
    @State
    public static class VolatileTest {
        volatile int v;
        @Actor
        public void actor1(II_Result r) {
            r.r1 = ++v;
        }
        @Actor
        public void actor2(II_Result r) {
            r.r2 = ++v;
        }
    }
}

/*
    In many cases, tests share the outcomes and other metadata. To common them,
    there is a special @JCStressMeta annotation that says to look up the metadata
    at another class.
    在一些情况下，测试需要共享输出结果和其他元数据，为了共享他们,有一个特殊的注解@JCStressMeta来指示其他类在另一个类里面查找元数据。
    How to run this test:
       $ java -jar jcstress-samples/target/jcstress.jar -t API_05_SharedMetadata
        ...
        .......... [OK] org.openjdk.jcstress.samples.api.APISample_05_SharedMetadata.PlainTest
          RESULT      SAMPLES    FREQ       EXPECT  DESCRIPTION
            1, 1    6,549,293    1.4%  Interesting  Both actors came up with the same value: atomicity failure.
            1, 2  414,490,076   90.0%   Acceptable  actor1 incremented, then actor2.
            2, 1   39,540,969    8.6%   Acceptable  actor2 incremented, then actor1.
        .......... [OK] org.openjdk.jcstress.samples.api.APISample_05_SharedMetadata.VolatileTest
          RESULT      SAMPLES    FREQ       EXPECT  DESCRIPTION
            1, 1   15,718,942    6.1%  Interesting  Both actors came up with the same value: atomicity failure.
            1, 2  120,855,601   47.2%   Acceptable  actor1 incremented, then actor2.
            2, 1  119,393,635   46.6%   Acceptable  actor2 incremented, then actor1.
 */
@Outcome(id = "1, 1", expect = ACCEPTABLE_INTERESTING, desc = "Both actors came up with the same value: atomicity failure.")
@Outcome(id = "1, 2", expect = ACCEPTABLE,             desc = "actor1 incremented, then actor2.")
@Outcome(id = "2, 1", expect = ACCEPTABLE,             desc = "actor2 incremented, then actor1.")
public class API_05_SharedMetadata {
    @JCStressTest
    @JCStressMeta(API_05_SharedMetadata.class)
    @State
    public static class PlainTest {
        int v;
        @Actor
        public void actor1(II_Result r) {
            r.r1 = ++v;
        }
        @Actor
        public void actor2(II_Result r) {
            r.r2 = ++v;
        }
    }
    @JCStressTest
    @JCStressMeta(API_05_SharedMetadata.class)
    @State
    public static class VolatileTest {
        volatile int v;
        @Actor
        public void actor1(II_Result r) {
            r.r1 = ++v;
        }
        @Actor
        public void actor2(II_Result r) {
            r.r2 = ++v;
        }
    }
}

/**
 * {@link JCStressMeta} points to another class with test meta-information.
 * @JCStressMeta注解将指向另一个包含测试元信息的类。
 * <p>When placed over {@link JCStressTest} class, the {@link Description}, {@link Outcome},
 * {@link Ref}, and other annotations will be inherited from the pointed class. This allows
 * to declare the description, grading and references only once for a group of tests.</p>
 *  JCStressMeta 
 * 当它和@JCStressTest一起出现，@Description、@Outcome、@Ref等其他注解将会从指向的类继承。这样就可以在一组测试中只声明一次描* 述、评分和参考信息
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface JCStressMeta {
    Class value();
}

/*
    JCStress also allows to put the descriptions and references right at the test.
    This helps to identify the goal for the test, as well as the discussions about
    the behavior in question.
 JCStress 还允许将引用和描述放入测试中,这将帮我们认清测试目标, 以及相关问题的讨论
    How to run this test:
       $ java -jar jcstress-samples/target/jcstress.jar -t API_06_Descriptions
 */
@JCStressTest
// Optional test description
@Description("Sample Hello World test")
// Optional references. @Ref is repeatable.
@Ref("http://openjdk.java.net/projects/code-tools/jcstress/")
@Outcome(id = "1, 1", expect = ACCEPTABLE_INTERESTING, desc = "Both actors came up with the same value: atomicity failure.")
@Outcome(id = "1, 2", expect = ACCEPTABLE,             desc = "actor1 incremented, then actor2.")
@Outcome(id = "2, 1", expect = ACCEPTABLE,             desc = "actor2 incremented, then actor1.")
@State
public class API_06_Descriptions {
    int v;
    @Actor
    public void actor1(II_Result r) {
        r.r1 = ++v;
    }
    @Actor
    public void actor2(II_Result r) {
        r.r2 = ++v;
    }
}