org.scalatest.events

# Ordinal

#### class Ordinal extends Ordered[Ordinal]

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 `Ordinal`s 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 `Ordinal`s, 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 `Ordinal`s 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 `Ordinal`s can be determined by first comparing the first element of the `List`s obtained by invoking `toList` on both `Ordinal`s. 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 `List`s until a position is found where the element values are not equal, or the end of one or both of the `List`s are reached. If the two `List`s are identical all the way to the end, and both `List`s have the same lengths, then the `Ordinal`s are equal. (Equal `Ordinal`s will not happen if correctly used by creating a new `Ordinal` for each fired event and each new `Suite`.). If the two `List`s 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)

attributes: final

authors:

1. Bill Venners

Inherited

1. Hide All
2. Show all

1. Ordered
2. Comparable
3. AnyRef
4. Any

Visibility

1. Public
2. All

### Instance constructors

1. #### new Ordinal(runStamp: Int)

   Construct a the first `Ordinal` for a run.

   Construct a the first `Ordinal` for a run.

   runStamp

     a number that identifies a particular run

### Value Members

1. #### def !=(arg0: AnyRef): Boolean

   attributes: final
   definition classes: AnyRef

2. #### def !=(arg0: Any): Boolean

   `o != arg0` is the same as `!(o == (arg0))`.

   `o != arg0` is the same as `!(o == (arg0))`.

   arg0

     the object to compare against this object for dis-equality.

   returns

     `false` if the receiver object is equivalent to the argument; `true` otherwise.

   attributes: final
   definition classes: Any

3. #### def ##(): Int

   attributes: final
   definition classes: AnyRef → Any

4. #### def $asInstanceOf[T0](): T0

   attributes: final
   definition classes: AnyRef

5. #### def $isInstanceOf[T0](): Boolean

   attributes: final
   definition classes: AnyRef

6. #### def <(that: Ordinal): Boolean

   definition classes: Ordered

7. #### def <=(that: Ordinal): Boolean

   definition classes: Ordered

8. #### def ==(arg0: AnyRef): Boolean

   `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)`.

   arg0

     the object to compare against this object for equality.

   returns

     `true` if the receiver object is equivalent to the argument; `false` otherwise.

   attributes: final
   definition classes: AnyRef

9. #### def ==(arg0: Any): Boolean

   `o == arg0` is the same as `o.equals(arg0)`.

   `o == arg0` is the same as `o.equals(arg0)`.

   arg0

     the object to compare against this object for equality.

   returns

     `true` if the receiver object is equivalent to the argument; `false` otherwise.

   attributes: final
   definition classes: Any

10. #### def >(that: Ordinal): Boolean

    definition classes: Ordered

11. #### def >=(that: Ordinal): Boolean

    definition classes: Ordered

12. #### def asInstanceOf[T0]: T0

    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.

    returns

      the receiver object.

    attributes: final
    definition classes: Any

13. #### def clone(): AnyRef

    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.

    returns

      a copy of the receiver object.

    attributes: protected
    definition classes: AnyRef

14. #### def compare(that: Ordinal): Int

    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.

    returns

      a negative integer, 0, or positive integer indicating this `Ordinal` is less than, equal to, or greater than the passed `Ordinal`.

    definition classes: Ordinal → Ordered

15. #### def compareTo(that: Ordinal): Int

    definition classes: Ordered → Comparable

16. #### def eq(arg0: AnyRef): Boolean

    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`).

    arg0

      the object to compare against this object for reference equality.

    returns

      `true` if the argument is a reference to the receiver object; `false` otherwise.

    attributes: final
    definition classes: AnyRef

17. #### def equals(other: Any): Boolean

    Indicates whether the passed object is equal to this one.

    Indicates whether the passed object is equal to this one.

    returns

      `true` if the receiver object is equivalent to the argument; `false` otherwise. */@param the object with which to compare this one for equality

    definition classes: Ordinal → AnyRef → Any

18. #### def finalize(): Unit

    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.

    attributes: protected
    definition classes: AnyRef

19. #### def getClass(): java.lang.Class[_ <: java.lang.Object]

    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.

    returns

      a representation that corresponds to the dynamic class of the receiver object.

    attributes: final
    definition classes: AnyRef

20. #### def hashCode(): Int

    Returns a hash code value for this object.

    Returns a hash code value for this object.

    definition classes: Ordinal → AnyRef → Any

21. #### def isInstanceOf[T0]: Boolean

    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.

    returns

      `true` if the receiver object is an instance of erasure of type `T0`; `false` otherwise.

    attributes: final
    definition classes: Any

22. #### def ne(arg0: AnyRef): Boolean

    `o.ne(arg0)` is the same as `!(o.eq(arg0))`.

    `o.ne(arg0)` is the same as `!(o.eq(arg0))`.

    arg0

      the object to compare against this object for reference dis-equality.

    returns

      `false` if the argument is not a reference to the receiver object; `true` otherwise.

    attributes: final
    definition classes: AnyRef

23. #### def next: Ordinal

    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.

24. #### def nextNewOldPair: (Ordinal, Ordinal)

    Construct two new `Ordinal`s, one for a new `Suite` about to be executed and one for the current `Suite` or other entity, such as a runner.

    Construct two new `Ordinal`s, 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 `Suite`s will be ordered before the next `Ordinal` for the current `Suite`.

25. #### def notify(): Unit

    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.

    attributes: final
    definition classes: AnyRef

26. #### def notifyAll(): Unit

    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.

    attributes: final
    definition classes: AnyRef

27. #### val runStamp: Int

28. #### def synchronized[T0](arg0: T0): T0

    attributes: final
    definition classes: AnyRef

29. #### def toList: List[Int]

    Returns a `List[Int]` representation of this `Ordinal`.

    Returns a `List[Int]` representation of this `Ordinal`. A set of `Ordinal`s 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 `Ordinal`s. The first element of the returned `List[Int]` is the `runStamp`.

30. #### def toString(): String

    Returns a string representation of the object.

    Returns a string representation of the object.

    The default representation is platform dependent.

    returns

      a string representation of the object.

    definition classes: AnyRef → Any

31. #### def wait(): Unit

    attributes: final
    definition classes: AnyRef

32. #### def wait(arg0: Long, arg1: Int): Unit

    attributes: final
    definition classes: AnyRef

33. #### def wait(arg0: Long): Unit

    attributes: final
    definition classes: AnyRef