src/core/global-value.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 4214 49039ae7bc3d
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  * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
    19  */
    20 #ifndef GLOBAL_VALUE_H
    21 #define GLOBAL_VALUE_H
    22 
    23 #include <string>
    24 #include <vector>
    25 #include "ptr.h"
    26 #include "attribute.h"
    27 
    28 
    29 namespace ns3 {
    30 
    31 /**
    32  * \ingroup Core
    33  *
    34  * \brief hold a so-called 'global value'.
    35  *
    36  * Instances of this class are expected to be allocated as static 
    37  * global variables and should be used to store configurable global state.
    38  * GlobalValues can be set directly by calling ns3::GlobalValue::SetValue
    39  * but they can also be set through the NS_GLOBAL_VALUE environment variable.
    40  * For example, NS_GLOBAL_VALUE='Name=Value;OtherName=OtherValue;' would set
    41  * global values Name and OtherName to Value and OtherValue respectively. 
    42  *
    43  * Users of the ns3::CommandLine class also get the ability to set global 
    44  * values through commandline arguments to their program: --Name=Value will
    45  * set global value Name to Value.
    46  */
    47 class GlobalValue
    48 {
    49   typedef std::vector<GlobalValue *> Vector;
    50 public:
    51   typedef Vector::const_iterator Iterator;
    52 
    53   /**
    54    * \param name the name of this global value.
    55    * \param help some help text which describes the purpose of this
    56    *        global value.
    57    * \param initialValue the value to assign to this global value
    58    *        during construction.
    59    * \param checker a pointer to an AttributeChecker which can verify
    60    *        that any user-supplied value to override the initial
    61    *        value matches the requested type constraints.
    62    */
    63   GlobalValue (std::string name, std::string help,
    64                const AttributeValue &initialValue,
    65                Ptr<const AttributeChecker> checker);
    66 
    67   /**
    68    * \returns the name of this GlobalValue.
    69    */
    70   std::string GetName (void) const;
    71   /**
    72    * \returns the help text of this GlobalValue.
    73    */
    74   std::string GetHelp (void) const;
    75   /**
    76    * \returns the current value of this GlobalValue.
    77    */
    78   void GetValue (AttributeValue &value) const;
    79   /**
    80    * \returns the checker associated to this GlobalValue.
    81    */
    82   Ptr<const AttributeChecker> GetChecker (void) const;
    83   /**
    84    * \param value the new value to set in this GlobalValue.
    85    */
    86   bool SetValue (const AttributeValue &value);
    87 
    88   /**
    89    * \param name the name of the global value
    90    * \param value the value to set in the requested global value.
    91    *
    92    * Iterate over the set of GlobalValues until a matching name is found
    93    * and then set its value with GlobalValue::SetValue.
    94    *
    95    * This method cannot fail. It will crash if the input is not valid.
    96    */
    97   static void Bind (std::string name, const AttributeValue &value);
    98   
    99   /**
   100    * \param name the name of the global value
   101    * \param value the value to set in the requested global value.
   102    * \returns true if the value could be set successfully, false otherwise.
   103    *
   104    * Iterate over the set of GlobalValues until a matching name is found
   105    * and then set its value with GlobalValue::SetValue.
   106    */
   107   static bool BindFailSafe (std::string name, const AttributeValue &value);
   108 
   109   /**
   110    * \returns an iterator which represents a pointer to the first GlobalValue registered.
   111    */
   112   static Iterator Begin (void);
   113   /**
   114    * \returns an iterator which represents a pointer to the last GlobalValue registered.
   115    */
   116   static Iterator End (void);
   117 private:
   118   friend class GlobalValueTests;
   119   static Vector *GetVector (void);
   120   void InitializeFromEnv (void);
   121   std::string m_name;
   122   std::string m_help;
   123   Ptr<AttributeValue> m_initialValue;
   124   Ptr<const AttributeChecker> m_checker;
   125 };
   126 
   127 } // namespace ns3
   128 
   129 #endif /* GLOBAL_VALUE_H */