Add a SingleEvent class.

src/simulator/event-collector.h

@@ -29,7 +29,10 @@ namespace ns3 {
 
 /**
  * \brief An object that tracks scheduled events and automatically
- * cancels them when it is destroyed.
+ * cancels them when it is destroyed.  It is useful in situations
+ * where multiple instances of the same type of event can
+ * simultaneously be scheduled, and when the events should be limited
+ * to the lifetime of a container object.
  */
 class EventCollector
 {

src/simulator/single-event.cc

@@ -0,0 +1,95 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2007 INESC Porto
+ * All rights reserved.
+ *
+ * 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: Gustavo J. A. M. Carneiro  <gjc@inescporto.pt>
+ */
+
+#ifdef RUN_SELF_TESTS
+
+#include "single-event.h"
+#include "ns3/test.h"
+
+namespace ns3 {
+
+class SingleEventTests : public Test
+{
+  int m_counter;
+  SingleEvent *m_events;
+
+  void SingleEventCallback ();
+
+public:
+
+  SingleEventTests ();
+  virtual ~SingleEventTests ();
+  virtual bool RunTests (void);
+};
+
+SingleEventTests::SingleEventTests ()
+  : Test ("SingleEvent"), m_counter (0), m_events (0)
+{}
+
+SingleEventTests::~SingleEventTests ()
+{}
+
+void
+SingleEventTests::SingleEventCallback ()
+{
+  m_counter++;
+}
+
+bool SingleEventTests::RunTests (void)
+{
+  bool result = true;
+
+
+  {
+    SingleEvent event;
+
+    event = Simulator::Schedule (Simulator::Now (), &SingleEventTests::SingleEventCallback, this);
+    Simulator::Run ();
+    NS_TEST_ASSERT_EQUAL (m_counter, 1);
+  }
+
+  {
+    SingleEvent event;
+
+    event = Simulator::Schedule (Simulator::Now (), &SingleEventTests::SingleEventCallback, this);
+  } // event is destroyed => the eventid cancelled
+
+  Simulator::Run ();
+  NS_TEST_ASSERT_EQUAL (m_counter, 1);
+
+  {
+    SingleEvent event;
+
+    event = Simulator::Schedule (Simulator::Now (), &SingleEventTests::SingleEventCallback, this);
+    // the second event cancels the first one
+    event = Simulator::Schedule (Simulator::Now (), &SingleEventTests::SingleEventCallback, this);
+    Simulator::Run ();
+    NS_TEST_ASSERT_EQUAL (m_counter, 2);
+  }
+
+  return result;
+}
+
+static SingleEventTests g_singleEventTests;
+    
+};
+
+#endif /* RUN_SELF_TESTS */

src/simulator/single-event.h

@@ -0,0 +1,84 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2007 INESC Porto
+ * All rights reserved.
+ *
+ * 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: Gustavo J. A. M. Carneiro  <gjc@inescporto.pt>
+ */
+#ifndef SINGLE_EVENT_H
+#define SINGLE_EVENT_H
+
+#include <list>
+#include "event-id.h"
+#include "simulator.h"
+
+namespace ns3 {
+
+/**
+ * \brief An object that tracks a single event
+ *
+ * A SingleEvent acts as a smart proxy for an EventId. It
+ * automatically cancels the underlying EventId when it is replaced
+ * for a new EventId, or when the SingleEvent is destroyed.  It is
+ * useful in situations where only one type of an event can possibly
+ * be scheduled at any single time (e.g. a single timer instance), and
+ * when the event should be limited to the lifetime of a container
+ * object.
+ */
+class SingleEvent
+{
+public:
+
+  SingleEvent ()
+  {}
+
+  /**
+   * \brief Tracks a newly scheduled event.
+   *
+   * Tracks a newly scheduled event.  Any previous event that may have
+   * been scheduled is first cancelled.
+   */
+  void operator = (const EventId &event)
+  {
+    Simulator::Cancel (m_event);
+    m_event = event;
+  }
+
+  /**
+   * \brief Retrives the event being tracked
+   *
+   * Returns a copy of the tracked event.  The returned value can be
+   * used to e.g. check if the event is still running, or to manually
+   * Cancel it.
+   */
+  EventId GetEvent () const
+  {
+    return m_event;
+  }
+
+  ~SingleEvent ()
+  {
+    Simulator::Cancel (m_event);
+  }
+
+private:
+
+  EventId m_event;
+};
+
+}; // namespace ns3
+
+#endif /* SINGLE_EVENT_H */

src/simulator/wscript

@@ -58,6 +58,7 @@ def build(bld):
         'timer.cc',
         'event-id.cc',
         'event-collector.cc',
+        'single-event.cc',
         'scheduler.cc',
         'scheduler-factory.cc',
         'scheduler-list.cc',
@@ -76,6 +77,7 @@ def build(bld):
         'timer.h',
         'event-id.h',
         'event-collector.h',
+        'single-event.h',
         'event-impl.h',
         'simulator.h',
         'scheduler.h',