ns3::EventLock Class Reference [Simulator]

Base class for locking functionality for events. More...

#include <event-impl.h>

Inherited by ns3::RealtimeEventLock.

List of all members.

---

Detailed Description

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 also:

EventImpl

---

The documentation for this class was generated from the following file:

• src/simulator/event-impl.h