com.google.testing.threadtester
Class InterleavedRunner

java.lang.Object
  com.google.testing.threadtester.InterleavedRunner

public class InterleavedRunner
extends Object

Utility class that tests two interleaved threads. The majority of methods in this class are designed to be used with instrumented classes, although there is one version of the interleave(MainRunnable, SecondaryRunnable, List) method that can be used with non-instrumented classes.

Author:

alasdair.mackintosh@gmail.com (Alasdair Mackintosh)

Method Summary

static <M extends MainRunnable<T>,T> RunResult	interleave(M main, SecondaryRunnable<T,M> secondary) Invokes two runnable instances, interleaving the execution.
static <M extends MainRunnable<T>,T> RunResult	interleave(M main, SecondaryRunnable<T,M> secondary, List<CodePosition> positions) Invokes two runnable instances, interleaving the execution.
static <M extends MainRunnable<T>,T> RunResult	interleaveAfter(M main, SecondaryRunnable<T,M> secondary, CodePosition position, int posCount) Invokes two runnable instances, interleaving the execution.
static <M extends MainRunnable<T>,T> RunResult	interleaveAtBreakpoint(M main, SecondaryRunnable<T,M> secondary, ReusableBreakpoint breakpoint) Version of interleave(MainRunnable, SecondaryRunnable, List) that takes a single ReusableBreakpoint
static RunResult	interleaveAtBreakpoint(Runnable mainRunnable, Runnable secondaryRunnable, ReusableBreakpoint breakpoint) Version of interleave(MainRunnable, SecondaryRunnable, List) that uses ordinary Runnables, and takes a single ReusableBreakpoint.
static <M extends MainRunnable<T>,T> RunResult	interleaveAtReusableBreakpoints(M main, SecondaryRunnable<T,M> secondary, List<ReusableBreakpoint> breakpoints) Invokes two runnable instances, interleaving the execution using the supplied list of ReusableBreakpoints.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

interleave

public static <M extends MainRunnable<T>,T> RunResult interleave(M main,
                                                                 SecondaryRunnable<T,M> secondary)

Invokes two runnable instances, interleaving the execution. The main runnable instance specifes an instrumented method that will be called. (See MainRunnable.getMethod(). If N is the number of executable lines in this method, then the main runnable will be executed N times, stopping at a different line each time. When the main runnable is stopped, the secondary runnable will be executed until it completes, and then the main runnable will continue. This allows a test to verify that the main method behaves correctly even if another method is called part way through its execution. Note that the framework will correctly handle the case where the second thread is blocked because of synchronization and/or locks in the first method.

Due to the structure of the method being tested, not every executable line may be reached. (E.g. conditional or error-handling blocks may not be entered.) The InterleavedRunner will attempt to break execution at every line, but if a given line is not reached, the runner will continue until the end of the test method.

Note that the method being tested must be instrumented. See ClassInstrumentation.

Parameters:

main - the main runnable

secondary - the secondary runnable

Returns:

a RunResult indicating any exceptions thrown by the two runnables.

Throws:

IllegalArgumentException - if the main runnable does not specify a valid instrumented class/method.

interleaveAfter

public static <M extends MainRunnable<T>,T> RunResult interleaveAfter(M main,
                                                                      SecondaryRunnable<T,M> secondary,
                                                                      CodePosition position,
                                                                      int posCount)

Invokes two runnable instances, interleaving the execution. This is identical to interleave(M, com.google.testing.threadtester.SecondaryRunnable), except that the main method will not stop until the given code position is reached the given number of times. This allows a test to simulate cases when a second thread is invoked after a certain condition. (E.g. an event is received after the main method registers a listener, but not before.)

Note that this method can only be invoked when the given runnables are calling a method in an instrumented class. See ClassInstrumentation.

Parameters:

main - the main runnable

secondary - the secondary runnable

position - the secondary runnable will not start until the first runnable has at least reached this position .

posCount - the number of time the first runnable must reach the given position

Returns:

a RunResult indicating any exceptions thrown by the two runnables.

Throws:

IllegalArgumentException - if the main runnable does not specify a valid instrumented class/method, or if the code position does not specify a position within the main method.

interleave

public static <M extends MainRunnable<T>,T> RunResult interleave(M main,
                                                                 SecondaryRunnable<T,M> secondary,
                                                                 List<CodePosition> positions)

Invokes two runnable instances, interleaving the execution. The main runnable will be executed once for each CodePosition in the list, stopping at each position in turn. When the main runnable is stopped, the secondary runnable will be executed until it completes, and then the main runnable will continue. This allows a test to verify that the main method behaves correctly even if another method is called part way through its execution. Note that the framework will correctly handle the case where the second thread is blocked because of synchronization and/or locks in the first method.

It is the caller's responsibility to ensure that the main runnable will reach the given positions when executing.

Note that the method being tested must be instrumented. See ClassInstrumentation.

Parameters:

main - the main runnable

secondary - the secondary runnable

positions - a list of code positions where the main runnable will stop

Returns:

a RunResult indicating any exceptions thrown by the two runnables.

Throws:

IllegalArgumentException - if the main runnable does not specify a valid instrumented class/method.

interleaveAtBreakpoint

public static RunResult interleaveAtBreakpoint(Runnable mainRunnable,
                                               Runnable secondaryRunnable,
                                               ReusableBreakpoint breakpoint)

Version of interleave(MainRunnable, SecondaryRunnable, List) that uses ordinary Runnables, and takes a single ReusableBreakpoint. Because there is only a single ReusableBreakpoint, the main and secondary Runnables will only be executed once, and hence do not need to go through the full lifecycle defined by the MainRunnable class.

interleaveAtBreakpoint

public static <M extends MainRunnable<T>,T> RunResult interleaveAtBreakpoint(M main,
                                                                             SecondaryRunnable<T,M> secondary,
                                                                             ReusableBreakpoint breakpoint)

Version of interleave(MainRunnable, SecondaryRunnable, List) that takes a single ReusableBreakpoint

interleaveAtReusableBreakpoints

public static <M extends MainRunnable<T>,T> RunResult interleaveAtReusableBreakpoints(M main,
                                                                                      SecondaryRunnable<T,M> secondary,
                                                                                      List<ReusableBreakpoint> breakpoints)

Invokes two runnable instances, interleaving the execution using the supplied list of ReusableBreakpoints. The main runnable will be executed once for every ReusableBreakpoint in the list, stopping at each ReusableBreakpoint in turn. When stopped, the secondary runnable will be executed until it completes, and then the main runnable will continue. This allows a test to verify that the main method behaves correctly even if another method is called part way through its execution. Note that the framework will correctly handle the case where the second thread is blocked because of synchronization and/or locks in the first method.

Internally, this method will create new Threads, and will invoke ReusableBreakpoint.setThread(java.lang.Thread) on the given ReusableBreakpoints, to ensure that the main runnable stops correctly.

Note that the methodName and class defined by the main runnable will be ignored. This method can be invoked even when the runnables are not calling into an instrumented method, provided that the given breakpoints do not require instrumentation. In general, this method is designed to be used with non-instrumented classes.

Returns:

a RunResult indicating any exceptions thrown by the two runnables.