Merge pull request #2707 from gdt/fix/signal-not-message

tests: Do not expect signals to be messages

tests/nutipc_ut.cpp

@@ -226,6 +226,7 @@ class TestSignalHandler: public nut::Signal::Handler {
 	virtual ~TestSignalHandler() override;
 };  // end of class TestSignalHandler
 
+// \todo Describe the point of this test.
 void NutIPCUnitTest::testSignalRecvQuick() {
 #ifdef WIN32
 	/* FIXME: Needs implementation for signals via pipes */
@@ -242,22 +243,52 @@ void NutIPCUnitTest::testSignalRecvQuick() {
 
 	pid_t my_pid = nut::Process::getPID();
 
-	/* NOTE: The signal order delivery is not specified by POSIX if several
-	 * ones arrive nearly simultaneously (and/or get confused by multi-CPU
-	 * routing). In this test we only verify that after sending several copies
-	 * of several signals, the expected counts of events were received.
+	/*
+	 * POSIX does not require signals to be delivered in order.
+	 * It does not require that signals are like messages, but
+	 * rather views them as a software version of hardware
+	 * interrupts.  Two sent signals might result in only one
+	 * handler invocation.  However, we (and most other signal
+	 * users) expect that signals are usually in order and usually
+	 * relatively promptly.
+	 *
+	 * For now, insist on beyond-POSIX behavior, as a canary that
+	 * if triggered, we should examine nut's use of signals.
 	 */
+
+	/* Send two signals, and pause briefly to allow delivery. */
 	CPPUNIT_ASSERT(0 == nut::Signal::send(nut::Signal::USER1, my_pid));
 	CPPUNIT_ASSERT(0 == nut::Signal::send(nut::Signal::USER2, my_pid));
+	::sleep(1);
+
+	/* Send two signals in the other order, and again pause briefly. */
 	CPPUNIT_ASSERT(0 == nut::Signal::send(nut::Signal::USER2, my_pid));
 	CPPUNIT_ASSERT(0 == nut::Signal::send(nut::Signal::USER1, my_pid));
+	::sleep(1);
+
+	/* Send a single signal. */
 	CPPUNIT_ASSERT(0 == nut::Signal::send(nut::Signal::USER1, my_pid));
 
-	// Let the sig. handler thread finish...
+	/*
+	 * Sleep 1s, assuming that is long enough for all signals to
+	 * be delivered (really, the last one) and the handler to have
+	 * run to completion.
+	 */
 	::sleep(1);
 
+	/*
+	 * Check that all 5 sent were received.  Note that strictly,
+	 * an OS on which USER1 and USER2 are each received once is
+	 * not a failure to conform.  But a delay of 1s in signal
+	 * delivery would generally be seen as not ok.
+	 */
 	CPPUNIT_ASSERT(caught_signals.size() == 5);
 
+	/*
+	 * Loop over the received signal records.  Count the number of
+	 * USER1 and USER2, and assert that no signals other than
+	 * those two were received.
+	 */
 	int countUSER1 = 0;
 	int countUSER2 = 0;
 	while (!caught_signals.empty()) {
@@ -275,6 +306,7 @@ void NutIPCUnitTest::testSignalRecvQuick() {
 		}
 	}
 
+	/* Check that received count matches sent count from code above. */
 	CPPUNIT_ASSERT(countUSER1 == 3);
 	CPPUNIT_ASSERT(countUSER2 == 2);
 #endif	/* WIN32 */