--- a/src/simulator/event-impl.h Tue Aug 26 08:42:28 2008 -0700
+++ b/src/simulator/event-impl.h Tue Aug 26 15:34:57 2008 -0700
@@ -21,11 +21,69 @@
#define EVENT_IMPL_H
#include <stdint.h>
+#include "ns3/system-mutex.h"
namespace ns3 {
/**
* \ingroup simulator
+ * \brief Base class for locking functionality for events.
+ *
+ * This class provides a cheap way (from the perspective of the event) to lock
+ * an event for multithreaded access. This is a bit of a hack, but it lets us
+ * use a whole lot of existing mechanism in the multithreaded simulator case.
+ *
+ * Here's a taste of the problem. It makes life extraordinarily easier in the
+ * case of interfacing real network devices to be able to have threads reading
+ * from real sockets and doing ScheduleNow calls to inject packets into ns-3.
+ * It is desirable to have Schedule* calls all work similarly as well. That is
+ * you don't want to have to do different calls when working from an "external"
+ * thread than you do when working in the context of the main simulation thread.
+ *
+ * It turns out that basically all of the Schedule* calls return an EventId.
+ * Each EventId holds a reference to the underlying event. Clients (see the
+ * Applications for examples) often schedule events and hold onto the EventId
+ * in case they need to cancel the event later. The EventImpl that underlies
+ * all of this is reference counted and sharing an unprotected reference
+ * counted object between threads is a bad thing.
+ *
+ * There were several possible solutions:
+ *
+ * - Put a mutex into each event (costs 40 bytes for the mutex and a minumum of
+ * three system calls to use an event);
+ * - Work on the inheritance diagram of EventImpl to make a
+ * MultithreadedEventImpl and pull apart all of the MakeEvent functions to
+ * teach them to make the right kind of event based on a flag returned by the
+ * simulator;
+ * - Rework the entire event mechanism to use raw pointers and avoid the entire
+ * reference counting approach with its associated problems;
+ * - Provide a cheap way to use a shared mutex (and avoid using the mutex in
+ * cases where it is not required).
+ *
+ * The original prototype chose the first option since it was easy. I am very
+ * hesitant to rework the entire event mechanism or even pull apart the MakeEvent
+ * code at this point. We went with the last option even though it feels a bit
+ * like a hack.
+ *
+ * The result is the EventLock class. If you have a simulator implementation that
+ * is going to need multithreaded access to events, you need to inherit from
+ * EventLock and provide a object that does real locking. Give the object to the
+ * EventImpl code by calling EventImpl::SetEventLock, take it back by calling
+ * EventImpl::SetNoEventLock or provide a new one. The EventImpl code takes no
+ * responsibility for the object passed in.
+ *
+ * \see EventImpl
+ */
+class EventLock
+{
+public:
+ virtual ~EventLock () {};
+ virtual void Lock (void) = 0;
+ virtual void Unlock (void) = 0;
+};
+
+/**
+ * \ingroup simulator
* \brief a simulation event
*
* Each subclass of this base class represents a simulation event. The
@@ -34,6 +92,8 @@
* obviously (there are Ref and Unref methods) reference-counted and
* most subclasses are usually created by one of the many Simulator::Schedule
* methods.
+ *
+ * \see EventLock
*/
class EventImpl
{
@@ -58,12 +118,31 @@
* Invoked by the simulation engine before calling Invoke.
*/
bool IsCancelled (void);
+
+ /**
+ * Provide a mutex with Lock and Unlock methods to the event implementation
+ * so that it can do cheap (from the perspective of event memory usage)
+ * critical sections (mutual exclusion) in the reference counting code.
+ *
+ * \param eventLock Pointer to the EventLock object used to contain the
+ * underlying mutex.
+ */
+ static void SetEventLock (EventLock *eventLock);
+ /**
+ * Remove any reference the event implementation code may hold to to an
+ * existing EventLock and disable the event locking feature.
+ *
+ * \see SetEventLock
+ */
+ static void SetNoEventLock (void);
+
protected:
virtual void Notify (void) = 0;
+
private:
- friend class Event;
bool m_cancel;
mutable uint32_t m_count;
+ static EventLock *m_eventLock;
};
}; // namespace ns3
@@ -73,13 +152,35 @@
void
EventImpl::Ref (void) const
{
- m_count++;
+ if (m_eventLock)
+ {
+ m_eventLock->Lock ();
+ m_count++;
+ m_eventLock->Unlock ();
+ }
+ else
+ {
+ m_count++;
+ }
}
+
void
EventImpl::Unref (void) const
{
- m_count--;
- if (m_count == 0)
+ register uint32_t c;
+
+ if (m_eventLock)
+ {
+ m_eventLock->Lock ();
+ c = --m_count;
+ m_eventLock->Unlock ();
+ }
+ else
+ {
+ c = --m_count;
+ }
+
+ if (c == 0)
{
delete this;
}