cleaned up lots of stuff (no functional changes)
ipc_stress_test runs all of the tests successfully now. In order to make
that work, I had to fix raw_queue_test so it didn't count the time spent
waiting for the fork() to complete as part of the timeout, and I cleaned
up various other parts at the same time.
Also improved some documentation and removed the mutex fairness tester
because it was slow, prone to random failures, and it's always been kind
of a fishy test.
diff --git a/aos/common/condition.h b/aos/common/condition.h
index 346ae54..c407070 100644
--- a/aos/common/condition.h
+++ b/aos/common/condition.h
@@ -7,8 +7,38 @@
namespace aos {
// A condition variable (IPC mechanism where 1 process/task can notify all
-// others that are waiting for something to happen).
-// This implementation will LOG(FATAL) if anything weird happens.
+// others that are waiting for something to happen) without the race condition
+// where a notification is sent after some process has checked if the thing has
+// happened but before it has started listening for notifications.
+//
+// This implementation will print debugging information and abort the process
+// if anything weird happens.
+//
+// A simple example of the use of a condition variable (adapted from
+// pthread_cond(3)):
+//
+// int x, y;
+// Mutex mutex;
+// Condition condition(&mutex);
+//
+// // Waiting until x is greater than y:
+// {
+// MutexLocker locker(&mutex);
+// while (!(x > y)) condition.Wait();
+// // do whatever
+// }
+//
+// // Modifying x and/or y:
+// {
+// MutexLocker locker(&mutex);
+// // modify x and y
+// if (x > y) condition.Broadcast();
+// }
+//
+// Notice the loop around the Wait(). This is very important because some other
+// process can lock the mutex and modify the shared state (possibly undoing
+// whatever the Wait()er was waiting for) in between the Broadcast()er unlocking
+// the mutex and the Wait()er(s) relocking it.
//
// Multiple condition variables may be associated with the same mutex but
// exactly 1 mutex must be associated with each condition variable.
@@ -18,9 +48,12 @@
// object will hold on to a reference to it but does not take ownership.
explicit Condition(Mutex *m);
- // Waits for the condition variable to be signalled, atomically unlocking m at
- // the same time. The mutex associated with this condition variable must be
- // locked when this is called and will be locked when this method returns.
+ // Waits for the condition variable to be signalled, atomically unlocking the
+ // mutex associated with this condition variable at the same time. The mutex
+ // associated with this condition variable must be locked when this is called
+ // and will be locked when this method returns.
+ // NOTE: The relocking of the mutex is not performed atomically with waking
+ // up.
void Wait();
// Signals at most 1 other process currently Wait()ing on this condition