cassandra-trunk/test/simulator/main/org/apache/cassandra/simulator/package-info.java
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The Simulator is a facility for deterministic pseudorandom execution of anything
 * from a snippet of code to an entire Cassandra cluster. A simulation execution
 * consists of an {@link org.apache.cassandra.simulator.ActionPlan} containing various
 * {@link org.apache.cassandra.simulator.Action} to simulate. Each {@code Action} represents
 * some discrete unit of simulation and its consequences - which are themselves {@code Action}s.
 * A simulation completes once all transitive consequences of the initial actions have completed.
 * The execution order is determined by an {@link org.apache.cassandra.simulator.ActionSchedule}
 * and its {@link org.apache.cassandra.simulator.RunnableActionScheduler} and
 * {@link org.apache.cassandra.simulator.FutureActionScheduler}.
 *
 * An {@code Action} may be simple, representing some simulation book-keeping or setup, but most
 * commonly derives from {@link org.apache.cassandra.simulator.systems.SimulatedAction}.
 * These simulated actions represent some execution context on an {@link org.apache.cassandra.simulator.systems.InterceptibleThread},
 * such as a task execution on an executor or a new thread. An {@code Action} is typically a one-shot
 * concept, but these threaded actions simultaneously represent any initial synchronous step taken
 * by a threaded execution context and the continuation of that state - through the creation of new
 * child and continuation {@code Action} that resume execution as the schedule demands. Note that such
 * a threaded action may have no consequences while still being in progress, e.g. when the thread enters
 * an unbounded wait condition, in which case it expects to be awoken by some other threaded action's
 * interaction with it.
 *
 * {@code Action} have various causality mechanisms to control their behaviour, in the form of {@link org.apache.cassandra.simulator.Action.Modifier}
 * options that may be applied to themselves, transitively to all of their descendants, or to specific verbs that are
 * consequences of a {@code SimulatedAction}. Also in the form of {@link org.apache.cassandra.simulator.OrderOn}
 * constraints that may force actions to occur in strictly sequential order, or simply to occur at some maximum rate.
 * This latter facility supports both the simulation of executor services and constraints for a correct simulation e.g.
 * when some action's children must occur in sequential order to correctly simulate some system operation.
 *
 * Simulation is achieved through various simulated systems ({@link org.apache.cassandra.simulator.systems})
 * and byte weaving ({@link org.apache.cassandra.simulator.asm}) of implementation classes, and chaos is introduced
 * via {@link org.apache.cassandra.simulator.cluster.KeyspaceActions} and also {@link org.apache.cassandra.utils.Nemesis}
 * points and on monitor entry and exit. Collectively these systems take control of: monitors, lock support, blocking
 * data structures, threads and executors, random number generation, time, paxos ballots, the network and failure detection.
 *
 * The first major simulation introduced was {@link org.apache.cassandra.simulator.paxos.PaxosSimulationRunner} which
 * may be invoked on the command line to simulate a cluster and some proportion of LWT read/write operations.
 *
 * For simulator simulation to operate correctly, be sure to run {@code ant simulator-jars} and to include the
 * following JVM parameters:
 *    -javaagent:/path/to/project.dir/build/test/lib/simulator-asm.jar
 *    -Xbootclasspath/a:/path/to/project.dir/build/test/lib/simulator-bootstrap.jar
 *    -Dlogback.configurationFile=file:///path/to/project.dir/test/conf/logback-simulator.xml
 *
 * For a reproducible simulation, make sure to use the same JVM and JDK for all runs, and to supply the following
 * JVM parameters:
 *    -XX:ActiveProcessorCount=???
 *    -Xmx???
 *    -XX:-BackgroundCompilation
 *    -XX:CICompilerCount=1
 *
 * For performance reasons the following parameters are recommended:
 *    -XX:Tier4CompileThreshold=1000
 *    -XX:-TieredCompilation
 *    -XX:ReservedCodeCacheSize=256M
 *
 * When debugging, the following parameters are recommended:
 *    -Dcassandra.test.simulator.livenesscheck=false
 *    -Dcassandra.test.simulator.debug=true
 *
 * Note also that when debugging the execution of arbitrary methods may modify the program output if these methods
 * invoke any simulated methods, notably if the method is synchronised or otherwise uses a monitor, or invokes
 * {@code System.identityHashCode} or a non-overidden {@code Object.hashCode()}, or many other scenarios.
 * To support debugging, this behaviour is switched off as far as possible when evaluating any {@code toString()}
 * method, but it is worth being prepared for the possibility that your use of the debugger has the potential to
 * perturb program execution.
 */
package org.apache.cassandra.simulator;