src/core/system-thread.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 3791 cf62138bd445
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
     1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
     2 /*
     3  * Copyright (c) 2008 INRIA
     4  *
     5  * This program is free software; you can redistribute it and/or modify
     6  * it under the terms of the GNU General Public License version 2 as
     7  * published by the Free Software Foundation;
     8  *
     9  * This program is distributed in the hope that it will be useful,
    10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    12  * GNU General Public License for more details.
    13  *
    14  * You should have received a copy of the GNU General Public License
    15  * along with this program; if not, write to the Free Software
    16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    17  *
    18  * Author: Mathieu Lacage <mathieu.lacage.inria.fr>
    19  */
    20 
    21 #ifndef SYSTEM_THREAD_H
    22 #define SYSTEM_THREAD_H
    23 
    24 #include "callback.h"
    25 
    26 namespace ns3 { 
    27 
    28 class SystemThreadImpl;
    29 
    30 /**
    31  * @brief A class which provides a relatively platform-independent thread
    32  * primitive.
    33  *
    34  * This class allows for creation of multiple threads of execution in a
    35  * process.  The exact implementation of the thread functionality is 
    36  * operating system dependent, but typically in ns-3 one is using an 
    37  * environment in which Posix Threads are supported (either navively or
    38  * in the case of Windows via Cygwin's implementation of pthreads on the 
    39  * Win32 API.  In either case we expect that these will be kernel-level
    40  * threads and therefore a system with multiple CPUs will see truly concurrent 
    41  * execution.
    42  *
    43  * Synchronization between threads is provided via the SystemMutex class.
    44  */
    45 class SystemThread 
    46 {
    47 public:
    48   /**
    49    * @brief Create a SystemThread object.
    50    *
    51    * A system thread object is not created running.  A thread of execution
    52    * must be explicitly started by calling the Start method.  When the 
    53    * Start method is called, it will spawn a thread of execution and cause
    54    * that thread to call out into the callback function provided here as
    55    * a parameter.
    56    *
    57    * Like all ns-3 callbacks, the provided callback may refer to a function
    58    * or a method of an object depending on how the MakeCallback function is
    59    * used.
    60    *
    61    * The most common use is expected to be creating a thread of execution in
    62    * a method.  In this case you would use code similar to,
    63    *
    64    *   MyClass myObject;
    65    *   Ptr<SystemThread> st = Create<SystemThread> (
    66    *     MakeCallback (&MyClass::MyMethod, &myObject));
    67    *   st->Start ();
    68    *
    69    * The SystemThread is passed a callback that calls out to the function
    70    * MyClass::MyMethod.  When this function is called, it is called as an
    71    * object method on the myObject object.  Essentially what you are doing
    72    * is asking the SystemThread to call object->MyMethod () in a new thread
    73    * of execution.
    74    *
    75    * Remember that if you are invoking a callback on an object that is
    76    * managed by a smart pointer, you need to call PeekPointer.
    77    *
    78    *   Ptr<MyClass> myPtr = Create<MyClass> ();
    79    *   Ptr<SystemThread> st = Create<SystemThread> (
    80    *     MakeCallback (&MyClass::MyMethod, PeekPointer (myPtr)));
    81    *   st->Start ();
    82    *
    83    * Just like any thread, you can synchronize with its termination.  The 
    84    * method provided to do this is Join (). If you call Join() you will block
    85    * until the SystemThread run method returns.
    86    *
    87    * @warning The SystemThread uses SIGALRM to wake threads that are possibly
    88    * blocked on IO.
    89    * @see Shutdown
    90    *
    91    * @warning I've made the system thread class look like a normal ns3 object
    92    * with smart pointers, and living in the heap.  This makes it very easy to
    93    * manage threads from a single master thread context.  You should be very
    94    * aware though that I have not made Ptr multithread safe!  This means that
    95    * if you pass Ptr<SystemThread> around in a multithreaded environment, it is
    96    * possible that the reference count will get messed up since it is not an
    97    * atomic operation.  CREATE AND MANAGE YOUR THREADS IN ONE PLACE -- LEAVE
    98    * THE PTR THERE.
    99    */
   100   SystemThread(Callback<void> callback);
   101 
   102   /**
   103    * @brief Destroy a SystemThread object.
   104    *
   105    */
   106   ~SystemThread();
   107 
   108   /**
   109    * Increment the reference count. This method should not be called
   110    * by user code. Object instances are expected to be used in conjunction
   111    * of the Ptr template which would make calling Ref unecessary and 
   112    * dangerous.
   113    */
   114   inline void Ref (void) const;
   115 
   116   /**
   117    * Decrement the reference count. This method should not be called
   118    * by user code. Object instances are expected to be used in conjunction
   119    * of the Ptr template which would make calling Ref unecessary and 
   120    * dangerous.
   121    */
   122   inline void Unref (void) const;
   123 
   124   /**
   125    * @brief Start a thread of execution, running the provided callback.
   126    */
   127   void Start (void);
   128 
   129   /**
   130    * @brief Suspend the caller until the thread of execution, running the 
   131    * provided callback, finishes.
   132    */
   133   void Join (void);
   134 
   135   /**
   136    * @brief Indicates to a managed thread doing cooperative multithreading that
   137    * its managing thread wants it to exit.
   138    *
   139    * It is often the case that we want a thread to be off doing work until such
   140    * time as its job is done (typically when the simulation is done).  We then 
   141    * want the thread to exit itself.  This method provides a consistent way for
   142    * the managing thread to communicate with the managed thread.  After the
   143    * manager thread calls this method, the Break() method will begin returning
   144    * true, telling the managed thread to exit.
   145    *
   146    * This alone isn't really enough to merit these events, but in Unix, if a
   147    * worker thread is doing blocking IO, it will need to be woken up from that
   148    * read somehow.  This method also provides that functionality, by sending a
   149    * SIGALRM signal to the possibly blocked thread.
   150    *
   151    * @warning Uses SIGALRM to notifiy threads possibly blocked on IO.  Beware
   152    * if you are using signals.
   153    * @see Break
   154    */
   155   void Shutdown (void);
   156 
   157   /**
   158    * @brief Indicates to a thread doing cooperative multithreading that
   159    * its managing thread wants it to exit.
   160    *
   161    * It is often the case that we want a thread to be off doing work until such
   162    * time as its job is done.  We then want the thread to exit itself.  This
   163    * method allows a thread to query whether or not it should be running.  
   164    * Typically, the worker thread is running in a forever-loop, and will need to
   165    * "break" out of that loop to exit -- thus the name.
   166    *
   167    * @see Shutdown
   168    * @returns true if thread is expected to exit (break out of the forever-loop)
   169    */
   170   bool Break (void);
   171 
   172 private:
   173   SystemThreadImpl * m_impl;
   174   mutable uint32_t m_count;
   175   bool m_break;
   176 };
   177 
   178  void
   179 SystemThread::Ref (void) const
   180 {
   181   m_count++;
   182 }
   183 
   184  void
   185 SystemThread::Unref (void) const
   186 {
   187   m_count--;
   188   if (m_count == 0)
   189     {
   190       delete this;
   191     }
   192 }
   193 
   194 } //namespace ns3
   195 
   196 #endif /* SYSTEM_THREAD_H */
   197 
   198