Add tests to SingleThreadedSchedulerClient() and document the memory model #13247

 123 | +    // create more threads than queues
 124 | +    // if the queues only permit execution of one task at once then
 125 | +    // the extra threads should effectively be doing nothing
 126 | +    // if they don't we'll get out of order behaviour
 127 | +    boost::thread_group threads;
 128 | +    for (int i = 0; i < 5; i++) {

---

 149 | +    // finish up
 150 | +    scheduler.stop(true);
 151 | +    threads.join_all();
 152 | +
 153 | +    BOOST_CHECK_EQUAL(counter1, 100);
 154 | +    BOOST_CHECK_EQUAL(counter2, 100);

---

  58 | + *
  59 | + * Events are totally ordered - that is - all CValidationInterface() subscribers
  60 | + * will receive callbacks in the same order. Furthermore, each ValidationInterface
  61 | + * subscriber may assume that callbacks effectively run in a single thread with
  62 | + * single-threaded memory consistency. That is, for a given ValidationInterface()
  63 | + * instantiation, each callback will complete before

---

  52 | @@ -53,6 +53,19 @@ void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
  53 |   */
  54 |  void SyncWithValidationInterfaceQueue();
  55 |  
  56 | +/**
  57 | + * Implement this to subscribe to validation events
  58 | + *
  59 | + * Events are totally ordered - that is - all CValidationInterface() subscribers

---

  85 | @@ -86,9 +86,9 @@ class CScheduler
  86 |  
  87 |  /**
  88 |   * Class used by CScheduler clients which may schedule multiple jobs
  89 | - * which are required to be run serially. Does not require such jobs
  90 | - * to be executed on the same thread, but no two jobs will be executed
  91 | - * at the same time.
  92 | + * which are required to be run serially. Jobs may not be run on the
  93 | + * same thread, but no two jobs will be executed
  94 | + * at the same time and memory will be sequentially consistent.

---