1 Copyright (c) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
   2 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3 
   4 This code is free software; you can redistribute it and/or modify it
   5 under the terms of the GNU General Public License version 2 only, as
   6 published by the Free Software Foundation.
   7 
   8 This code is distributed in the hope that it will be useful, but WITHOUT
   9 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11 version 2 for more details (a copy is included in the LICENSE file that
  12 accompanied this code).
  13 
  14 You should have received a copy of the GNU General Public License version
  15 2 along with this work; if not, write to the Free Software Foundation,
  16 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  17 
  18 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  19 or visit www.oracle.com if you need additional information or have any
  20 questions.
  21 
  22 The Churn tests are a series of small programs designed to
  23 simply churn memory over, mixing in calls to GC and Finalization.
  24 They are all basically the same program with permutations.
  25 Each program contains:
  26 
  27 LocalRandom class -- used to isloate calls to random generator
  28         for reproducibility
  29 
  30 MemoryObject class -- simply allocated and reclaimed. contains
  31         a byte array
  32 
  33 Churn class -- entry point. Allocates threads and counts objects.
  34         When loop is done, sets Semaphore to signal threads to cease
  35 
  36 ThreadObject class -- allocates and deallocates (by assignment)
  37         MemoryObjects
  38 
  39 SemaphoreObject class -- static class for signalling threads when
  40         to stop running. Perhap poorly named.
  41 
  42 CommandLine class -- parses command line args. Static class.
  43 --------------------------
  44 Usage:
  45 
  46 java Churn [-l numberOfLoops] [-t numberOfThreads] [-a sizeOfArray] [-m multiplier] [-f <run forever>] [-s seed]
  47 
  48 NOTE: the options can be passed in any order
  49 
  50 
  51 seed is the seed for the LocalRandom pseudo-random generator
  52 
  53 numberOfLoops is the number of iterations a test will go through.
  54 This defaults to 2000
  55 
  56 numberOfThreads is the number of threads activating and deactivating
  57 MemoryObjects. This deaults to 2.
  58 
  59 sizeOfArray is the number of MemoryObjects each thread manipulates.
  60 This defaults to 1024.
  61 
  62 multiplier is a value used to determine how much memory each MemoryObject
  63 holds. It defaults to 10.
  64 
  65 The tests can be configured to run forever by passing -f on the
  66 command line. This is useful for continued stress testing outside
  67 of a test harness.
  68 -----------------------------
  69 The total amount of needed memory is approximately
  70 numberOfThreads * (sizeOfArray * sizeOfArray) * (multiplier / 2) bytes
  71 
  72 The default is about 10 Megs needed, not couting garbage collection
  73 overhead.  Garbage collection doubles the memory requirements for
  74 programs that run out of heap space, so the the true default size
  75 is 20 Megs.
  76 
  77 
  78 Testname        What it does
  79 -------------   ---------------------------------------------------------
  80 Churn1          Simply creates new MemObjects. No finalizers. No user
  81                 calls to System.gc(). Count of objects simply grows
  82                 since no method ever decreases the count -- object count
  83                 equals total objects ever allocated. Memory used is
  84                 approx = (object count) * (array size) * (multiplier) / 2
  85 
  86 Churn2          Same as Churn1, but adds a call to System.gc() every loop.
  87                 Object Count should simply increase. About half the time,
  88                 this test will hang before the 100th loop. About 10% of
  89                 the time this test will SEG FAULT with either a BUS ERROR
  90                 or ACCESS VIOLATION
  91 
  92 Churn3          Same as Churn1, but the MemoryObject class has a
  93                 finalize() method on it. The method is empty. The objecty
  94                 count should continue to rise. However, this program
  95                 runs out of memory after around 35 loops. The threads
  96                 dies from OutOfMemoryErrors. It looks as if the
  97                 finalizers are not called fast enough during GC, so
  98                 enough memory cannot be freed.
  99                 Additionally, about 10% of the time, this program SEGFAULTS
 100 
 101 Churn3a         Same as Churn3, but with an explicit call to
 102                 System.runFinalization() in each loop.
 103                 Occasionally, this test will run out of memory
 104                 early on for one or more of the threads.
 105                 Also, this test sometimes hangs, even if one or
 106                 all of the ThreadObjects have died.
 107                 Even if no threads die, and it doesn't hang, this
 108                 program will still die with:
 109                         java.lang.NullPointerException
 110                                 at java.lang.String.indexOf(String.java)
 111                                 at Churn3a.main(Churn3a.java:71)
 112                 which contains only a call to join()
 113 
 114 
 115 
 116 Churn4          Same as Churn3, but with code in the finalize method
 117                 which would decrement a *static* field in the class.
 118                 This test runs out of memory much more quickly, something
 119                 like after 3 or 4 loops.