Class used to specify a sequential order for events reported during a test run, so they can be arranged in that order in a report even if the events were fired in some other order during concurrent or distributed execution.
An Ordinal is an immutable object holding a run stamp and a sequence
of stamps.
The run stamp is an integer that identifies a particular run. All events
reported during the same run should share the same run stamp. By contrast, each
event reported during a particular run should have a different stamps sequence.
One use case for the run stamp is that the initial run from ScalaTest's GUI
will have run stamp 0. Subsequent reruns will have run stamps 1,
2, 3, etc., so that reports in the GUI can simply be sorted in "ordinal" order. Another
use case is a set of servers used to run multiple tests simultaneously in a distributed
fashion. The run stamp can be used to identify the run for which an event belongs.
The stamps sequence is designed to allow a sequential order of events to be specified during
concurrent execution of ScalaTest suites. ScalaTest's model for concurrent execution is that
the suites that make up a run may be executed concurrently, but the tests within a single suite
will be executed sequentially. In addition to tests, suites may contain nested suites. The default implementation
of execute in class Suite will first invoke runNestedSuites and
then runTests. If no Distributor is passed to execute, the
runNestedSuites method will execute the nested suites sequentially via the same thread
that invoked runNestedSuites. As a result, suites will by default executed in depth first order
when executed sequentially. If a Distributor is passed to execute, the
runNestedSuites method will simply put its nested suites into the Distributor
and return. Some other threads or processes must then execute those nested suites. Given the default
implementations of execute and runNestedSuites described here, the Ordinal
will allow the events from a concurrent run to be sorted in the same depth-first order that the events
from a corresponding sequential run would arrive.
Each event reported during a run should be given a unique Ordinal. An Ordinal is required
by all Event subclasses, instances of which are used to send information to the report
function passed to a Suite's execute method. The first Ordinal for a run
can be produced be passing a run stamp to Ordinal's lone public constructor:
val firstOrdinal = new Ordinal(99)
The run stamp can be any integer. The Ordinal created in this way can be passed along with the first
reported event of the run, such as a RunStarting event. Thereafter, new Ordinals for the same run
can be obtained by calling either next or nextNewOldPair on the previously obtained Ordinal.
In other words, given an Ordinal, you can obtain the next Ordinal by invoking one of these two
"next" methods on the Ordinal you have in hand. Before executing a new Suite, the nextNewOldPair
method should be invoked. This will return two new Ordinals, one for the new Suite about to be executed, and
one for the currently executing entity (either a Suite or some sort of test runner). At any other time, the next Ordinal
can be obtained by simply invoking next on the current Ordinal.
You can convert an Ordinal to a List by invoking toList on it. The resulting List will contain
the run stamp as its first element, and the contents of its stamps sequence as the subsequent elements. The stamps
sequence will initially be composed of a single element with the value 0. Thus, toList invoked on the firstOrdinal shown above will
result in:
firstOrdinal.toList // results in: List(99, 0)
Each time next is invoked, the rightmost integer returned by toList will increment:
val secondOrdinal = firstOrdinal.next secondOrdinal.toList // results in: List(99, 1)val thirdOrdinal = secondOrdinal.next thirdOrdinal.toList // result is : List(99, 2)
When nextNewOldPair is invoked the result will be a tuple whose first element is the first Ordinal for
the new Suite about to be executed (for example, a nested Suite of the currently executing Suite). The
second element is the next Ordinal for the currently executing Suite or other entity:
val (nextForNewSuite, nextForThisRunner) = thirdOrdinal.nextNewOldPair nextForNewSuite.toList // results in: (99, 2, 0) nextForThisRunner.toList // results in: (99, 3)
The toList method of the Ordinal for the new suite starts with the same sequence of elements as the Ordinal from which it was
created, but has one more element, a 0, appended at the end. Subsequent invocations of next on this series of Ordinals will
increment that last element:
val newSuiteOrdinal2 = nextForNewSuite.next newSuiteOrdinal2.toList // results in: List(99, 2, 1)val newSuiteOrdinal3 = newSuiteOrdinal2.next newSuiteOrdinal3.toList // result is : List(99, 2, 2)
This behavior allows events fired by Suite running concurrently to be reordered in a pre-determined sequence after all the events
have been reported. The ordering of two Ordinals can be determined by first comparing the first element of the Lists obtained
by invoking toList on both Ordinals. These values represent the runStamp. If one run stamp is a lower number than
the other, that Ordinal comes first. For example, an Ordinal with a run stamp of 98 is ordered before an Ordinal with
a run stamp of 99. If the run stamps are equal, the next number in the list is inspected. As with the run stamps, an Ordinal with a lower
number is ordered before an Ordinal with a higher number. If two corresponding elements are equal, the next pair of elements will be inspected.
This will continue no down the length of the Lists until a position is found where the element values are not equal, or the end of one or both of
the Lists are reached. If the two Lists are identical all the way to the end, and both Lists have the same lengths,
then the Ordinals are equal. (Equal Ordinals will not happen if correctly used by creating a new Ordinal for
each fired event and each new Suite.). If the two Lists are identical all the way to the end of one, but the other List
is longer (has more elements), then the shorter list is ordered before the longer one.
As an example, here are some Ordinal List forms in order:
List(99, 0) List(99, 1) List(99, 2) List(99, 2, 0) List(99, 2, 1) List(99, 2, 2) List(99, 2, 2, 0) List(99, 2, 2, 1) List(99, 2, 2, 2) List(99, 2, 3) List(99, 2, 4) List(99, 2, 4, 0) List(99, 2, 4, 1) List(99, 2, 4, 2) List(99, 3) List(99, 4) List(99, 4, 0) List(99, 4, 1) List(99, 5)
o != arg0 is the same as !(o == (arg0)).
o != arg0 is the same as !(o == (arg0)).
the object to compare against this object for dis-equality.
false if the receiver object is equivalent to the argument; true otherwise.
o == arg0 is the same as if (o eq null) arg0 eq null else o.equals(arg0).
o == arg0 is the same as if (o eq null) arg0 eq null else o.equals(arg0).
the object to compare against this object for equality.
true if the receiver object is equivalent to the argument; false otherwise.
o == arg0 is the same as o.equals(arg0).
o == arg0 is the same as o.equals(arg0).
the object to compare against this object for equality.
true if the receiver object is equivalent to the argument; false otherwise.
This method is used to cast the receiver object to be of type T0.
This method is used to cast the receiver object to be of type T0.
Note that the success of a cast at runtime is modulo Scala's erasure semantics. Therefore the expression
1.asInstanceOf[String] will throw a ClassCastException at runtime, while the expression
List(1).asInstanceOf[List[String]] will not. In the latter example, because the type argument is erased as
part of compilation it is not possible to check whether the contents of the list are of the requested typed.
the receiver object.
This method creates and returns a copy of the receiver object.
This method creates and returns a copy of the receiver object.
The default implementation of the clone method is platform dependent.
a copy of the receiver object.
Compares this Ordinal with the passed Ordinal for order.
Compares this Ordinal with the passed Ordinal for order. If this object is "less than" (ordered before)
the passed object, compare will return a negative integer. If this class is "greater than" (ordered after)
the passed object, compare will return a positive integer. Otherwise, this Ordinal is equal to
the passed object, and compare will return 0.
a negative integer, 0, or positive integer indicating this Ordinal is less than, equal to, or greater than the passed Ordinal.
This method is used to test whether the argument (arg0) is a reference to the
receiver object (this).
This method is used to test whether the argument (arg0) is a reference to the
receiver object (this).
The eq method implements an [http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation] on
non-null instances of AnyRef:
* It is reflexive: for any non-null instance x of type AnyRef, x.eq(x) returns true.
* It is symmetric: for any non-null instances x and y of type AnyRef, x.eq(y) returns true if and
only if y.eq(x) returns true.
* It is transitive: for any non-null instances x, y, and z of type AnyRef if x.eq(y) returns true
and y.eq(z) returns true, then x.eq(z) returns true.
Additionally, the eq method has three other properties.
* It is consistent: for any non-null instances x and y of type AnyRef, multiple invocations of
x.eq(y) consistently returns true or consistently returns false.
* For any non-null instance x of type AnyRef, x.eq(null) and null.eq(x) returns false.
* null.eq(null) returns true.
When overriding the equals or hashCode methods, it is important to ensure that their behavior is
consistent with reference equality. Therefore, if two objects are references to each other (o1 eq o2), they
should be equal to each other (o1 == o2) and they should hash to the same value (o1.hashCode == o2.hashCode).
the object to compare against this object for reference equality.
true if the argument is a reference to the receiver object; false otherwise.
Indicates whether the passed object is equal to this one.
Indicates whether the passed object is equal to this one.
true if the passed object is equal to this one
This method is called by the garbage collector on the receiver object when garbage collection determines that there are no more references to the object.
This method is called by the garbage collector on the receiver object when garbage collection determines that there are no more references to the object.
The details of when and if the finalize method are invoked, as well as the interaction between finalize
and non-local returns and exceptions, are all platform dependent.
Returns a representation that corresponds to the dynamic class of the receiver object.
Returns a representation that corresponds to the dynamic class of the receiver object.
The nature of the representation is platform dependent.
a representation that corresponds to the dynamic class of the receiver object.
Returns a hash code value for this object.
Returns a hash code value for this object.
a hash code for this object
This method is used to test whether the dynamic type of the receiver object is T0.
This method is used to test whether the dynamic type of the receiver object is T0.
Note that the test result of the test is modulo Scala's erasure semantics. Therefore the expression
1.isInstanceOf[String] will return false, while the expression List(1).isInstanceOf[List[String]] will
return true. In the latter example, because the type argument is erased as part of compilation it is not
possible to check whether the contents of the list are of the requested typed.
true if the receiver object is an instance of erasure of type T0; false otherwise.
o.ne(arg0) is the same as !(o.eq(arg0)).
o.ne(arg0) is the same as !(o.eq(arg0)).
the object to compare against this object for reference dis-equality.
false if the argument is not a reference to the receiver object; true otherwise.
Construct the next Ordinal for the current suite or other entity, such as a runner.
Construct the next Ordinal for the current suite or other entity, such as a runner.
Construct two new Ordinals, one for a new Suite about to be executed and
one for the current Suite or other entity, such as a runner. The Ordinal
for the new Suite is the first (_1) element in the tuple:
Construct two new Ordinals, one for a new Suite about to be executed and
one for the current Suite or other entity, such as a runner. The Ordinal
for the new Suite is the first (_1) element in the tuple:
val (nextOrdinalForNewSuite, nextOrdinalForThisSuite) currentOrdinal.nextNewOldPair
The reason the next Ordinal for the new Suite is first is because it will
be ordered before the next Ordinal for the current Suite (or other
entity such as a runner). In fact, any event reported within the context of the new Suite or
its nested Suites will be ordered before the next Ordinal for the current Suite.
a tuple whose first element is the first Ordinal for the new Suite and whose
second element is the next Ordinal for the current Suite or other entity, such
as a runner.
Wakes up a single thread that is waiting on the receiver object's monitor.
Wakes up a single thread that is waiting on the receiver object's monitor.
Wakes up all threads that are waiting on the receiver object's monitor.
Wakes up all threads that are waiting on the receiver object's monitor.
Returns a List[Int] representation of this Ordinal. A set of Ordinals will be ordered
in the same order as the set of List[Int]s that are returned by invoking this method on each of the Ordinals.
Returns a List[Int] representation of this Ordinal. A set of Ordinals will be ordered
in the same order as the set of List[Int]s that are returned by invoking this method on each of the Ordinals.
The first element of the returned List[Int] is the runStamp.
a List[Int] representation of this Ordinal.
Returns a string representation of the object.
Returns a string representation of the object.
The default representation is platform dependent.
a string representation of the object.
Class used to specify a sequential order for events reported during a test run, so they can be arranged in that order in a report even if the events were fired in some other order during concurrent or distributed execution.
An
Ordinalis an immutable object holding a run stamp and a sequence of stamps. The run stamp is an integer that identifies a particular run. All events reported during the same run should share the same run stamp. By contrast, each event reported during a particular run should have a different stamps sequence. One use case for the run stamp is that the initial run from ScalaTest's GUI will have run stamp 0. Subsequent reruns will have run stamps 1, 2, 3, etc., so that reports in the GUI can simply be sorted in "ordinal" order. Another use case is a set of servers used to run multiple tests simultaneously in a distributed fashion. The run stamp can be used to identify the run for which an event belongs.The stamps sequence is designed to allow a sequential order of events to be specified during concurrent execution of ScalaTest suites. ScalaTest's model for concurrent execution is that the suites that make up a run may be executed concurrently, but the tests within a single suite will be executed sequentially. In addition to tests, suites may contain nested suites. The default implementation of
executein classSuitewill first invokerunNestedSuitesand thenrunTests. If noDistributoris passed toexecute, therunNestedSuitesmethod will execute the nested suites sequentially via the same thread that invokedrunNestedSuites. As a result, suites will by default executed in depth first order when executed sequentially. If aDistributoris passed toexecute, therunNestedSuitesmethod will simply put its nested suites into theDistributorand return. Some other threads or processes must then execute those nested suites. Given the default implementations ofexecuteandrunNestedSuitesdescribed here, theOrdinalwill allow the events from a concurrent run to be sorted in the same depth-first order that the events from a corresponding sequential run would arrive.Each event reported during a run should be given a unique
Ordinal. AnOrdinalis required by allEventsubclasses, instances of which are used to send information to thereportfunction passed to aSuite'sexecutemethod. The firstOrdinalfor a run can be produced be passing a run stamp toOrdinal's lone public constructor:The run stamp can be any integer. The
Ordinalcreated in this way can be passed along with the first reported event of the run, such as aRunStartingevent. Thereafter, newOrdinals for the same run can be obtained by calling eithernextornextNewOldPairon the previously obtainedOrdinal. In other words, given anOrdinal, you can obtain the nextOrdinalby invoking one of these two "next" methods on theOrdinalyou have in hand. Before executing a newSuite, thenextNewOldPairmethod should be invoked. This will return two newOrdinals, one for the newSuiteabout to be executed, and one for the currently executing entity (either aSuiteor some sort of test runner). At any other time, the nextOrdinalcan be obtained by simply invokingnexton the currentOrdinal.You can convert an
Ordinalto aListby invokingtoListon it. The resultingListwill contain the run stamp as its first element, and the contents of its stamps sequence as the subsequent elements. The stamps sequence will initially be composed of a single element with the value 0. Thus,toListinvoked on thefirstOrdinalshown above will result in:Each time
nextis invoked, the rightmost integer returned bytoListwill increment:When
nextNewOldPairis invoked the result will be a tuple whose first element is the firstOrdinalfor the newSuiteabout to be executed (for example, a nestedSuiteof the currently executingSuite). The second element is the nextOrdinalfor the currently executingSuiteor other entity:The
toListmethod of theOrdinalfor the new suite starts with the same sequence of elements as theOrdinalfrom which it was created, but has one more element, a 0, appended at the end. Subsequent invocations ofnexton this series ofOrdinals will increment that last element:This behavior allows events fired by
Suiterunning concurrently to be reordered in a pre-determined sequence after all the events have been reported. The ordering of twoOrdinals can be determined by first comparing the first element of theLists obtained by invokingtoListon bothOrdinals. These values represent therunStamp. If one run stamp is a lower number than the other, thatOrdinalcomes first. For example, anOrdinalwith a run stamp of 98 is ordered before anOrdinalwith a run stamp of 99. If the run stamps are equal, the next number in the list is inspected. As with the run stamps, anOrdinalwith a lower number is ordered before anOrdinalwith a higher number. If two corresponding elements are equal, the next pair of elements will be inspected. This will continue no down the length of theLists until a position is found where the element values are not equal, or the end of one or both of theLists are reached. If the twoLists are identical all the way to the end, and bothLists have the same lengths, then theOrdinals are equal. (EqualOrdinals will not happen if correctly used by creating a newOrdinalfor each fired event and each newSuite.). If the twoLists are identical all the way to the end of one, but the otherListis longer (has more elements), then the shorter list is ordered before the longer one.As an example, here are some
OrdinalListforms in order: