Detect the pthread.h header file and automatically disable components that cannot build without it.
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) 2005,2006 INRIA
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation;
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
*/
#ifndef EVENT_IMPL_H
#define EVENT_IMPL_H
#include <stdint.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
* EventImpl::Invoke method will be invoked by the simulation engine
* when the time associated to this event expires. This class is
* 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
{
public:
EventImpl ();
inline void Ref (void) const;
inline void Unref (void) const;
virtual ~EventImpl () = 0;
/**
* Called by the simulation engine to notify the event that it has expired.
*/
void Invoke (void);
/**
* Marks the event as 'canceled'. The event will not be removed from
* the event list but the simulation engine will check its canceled status
* before calling Invoke.
*/
void Cancel (void);
/**
* \returns true if the event has been canceled.
*
* 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:
bool m_cancel;
mutable uint32_t m_count;
static EventLock *m_eventLock;
};
}; // namespace ns3
namespace ns3 {
void
EventImpl::Ref (void) const
{
if (m_eventLock)
{
m_eventLock->Lock ();
m_count++;
m_eventLock->Unlock ();
}
else
{
m_count++;
}
}
void
EventImpl::Unref (void) const
{
uint32_t c;
if (m_eventLock)
{
m_eventLock->Lock ();
c = --m_count;
m_eventLock->Unlock ();
}
else
{
c = --m_count;
}
if (c == 0)
{
delete this;
}
}
} // namespace ns3
#endif /* EVENT_IMPL_H */