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
mathieu@2581
     1
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
mathieu@2581
     2
/*
mathieu@2581
     3
 * Copyright (c) 2008 INRIA
mathieu@2581
     4
 *
mathieu@2581
     5
 * This program is free software; you can redistribute it and/or modify
mathieu@2581
     6
 * it under the terms of the GNU General Public License version 2 as
mathieu@2581
     7
 * published by the Free Software Foundation;
mathieu@2581
     8
 *
mathieu@2581
     9
 * This program is distributed in the hope that it will be useful,
mathieu@2581
    10
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
mathieu@2581
    11
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
mathieu@2581
    12
 * GNU General Public License for more details.
mathieu@2581
    13
 *
mathieu@2581
    14
 * You should have received a copy of the GNU General Public License
mathieu@2581
    15
 * along with this program; if not, write to the Free Software
mathieu@2581
    16
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
mathieu@2581
    17
 *
mathieu@2581
    18
 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
mathieu@2581
    19
 */
mathieu@2467
    20
#ifndef GLOBAL_VALUE_H
mathieu@2467
    21
#define GLOBAL_VALUE_H
mathieu@2429
    22
mathieu@2429
    23
#include <string>
mathieu@2429
    24
#include <vector>
mathieu@2429
    25
#include "ptr.h"
mathieu@2438
    26
#include "attribute.h"
mathieu@2429
    27
mathieu@2429
    28
mathieu@2429
    29
namespace ns3 {
mathieu@2429
    30
mathieu@2584
    31
/**
tomh@3182
    32
 * \ingroup Core
tomh@3182
    33
 *
mathieu@2584
    34
 * \brief hold a so-called 'global value'.
mathieu@2584
    35
 *
mathieu@2584
    36
 * Instances of this class are expected to be allocated as static 
mathieu@2584
    37
 * global variables and should be used to store configurable global state.
mathieu@4638
    38
 * GlobalValues can be set directly by calling ns3::GlobalValue::SetValue
mathieu@4638
    39
 * but they can also be set through the NS_GLOBAL_VALUE environment variable.
mathieu@4638
    40
 * For example, NS_GLOBAL_VALUE='Name=Value;OtherName=OtherValue;' would set
mathieu@4638
    41
 * global values Name and OtherName to Value and OtherValue respectively. 
mathieu@4638
    42
 *
mathieu@4638
    43
 * Users of the ns3::CommandLine class also get the ability to set global 
mathieu@4638
    44
 * values through commandline arguments to their program: --Name=Value will
mathieu@4638
    45
 * set global value Name to Value.
mathieu@2584
    46
 */
mathieu@2467
    47
class GlobalValue
mathieu@2429
    48
{
mathieu@2467
    49
  typedef std::vector<GlobalValue *> Vector;
mathieu@2429
    50
public:
mathieu@2429
    51
  typedef Vector::const_iterator Iterator;
mathieu@2429
    52
mathieu@2584
    53
  /**
mathieu@2584
    54
   * \param name the name of this global value.
mathieu@2584
    55
   * \param help some help text which describes the purpose of this
mathieu@2584
    56
   *        global value.
mathieu@2584
    57
   * \param initialValue the value to assign to this global value
mathieu@2584
    58
   *        during construction.
mathieu@2584
    59
   * \param checker a pointer to an AttributeChecker which can verify
mathieu@2584
    60
   *        that any user-supplied value to override the initial
mathieu@2584
    61
   *        value matches the requested type constraints.
mathieu@2584
    62
   */
mathieu@2467
    63
  GlobalValue (std::string name, std::string help,
mathieu@2965
    64
               const AttributeValue &initialValue,
mathieu@2965
    65
               Ptr<const AttributeChecker> checker);
mathieu@2429
    66
mathieu@2584
    67
  /**
mathieu@2584
    68
   * \returns the name of this GlobalValue.
mathieu@2584
    69
   */
mathieu@2429
    70
  std::string GetName (void) const;
mathieu@2584
    71
  /**
mathieu@2584
    72
   * \returns the help text of this GlobalValue.
mathieu@2584
    73
   */
mathieu@2429
    74
  std::string GetHelp (void) const;
mathieu@2584
    75
  /**
mathieu@2584
    76
   * \returns the current value of this GlobalValue.
mathieu@2584
    77
   */
mathieu@2965
    78
  void GetValue (AttributeValue &value) const;
mathieu@2584
    79
  /**
mathieu@2584
    80
   * \returns the checker associated to this GlobalValue.
mathieu@2584
    81
   */
mathieu@2429
    82
  Ptr<const AttributeChecker> GetChecker (void) const;
mathieu@2584
    83
  /**
mathieu@2584
    84
   * \param value the new value to set in this GlobalValue.
mathieu@2584
    85
   */
mathieu@2965
    86
  bool SetValue (const AttributeValue &value);
mathieu@2429
    87
mathieu@2584
    88
  /**
mathieu@2584
    89
   * \param name the name of the global value
mathieu@2584
    90
   * \param value the value to set in the requested global value.
mathieu@2584
    91
   *
mathieu@2584
    92
   * Iterate over the set of GlobalValues until a matching name is found
mathieu@2584
    93
   * and then set its value with GlobalValue::SetValue.
mathieu@2584
    94
   *
mathieu@2584
    95
   * This method cannot fail. It will crash if the input is not valid.
mathieu@2584
    96
   */
mathieu@2965
    97
  static void Bind (std::string name, const AttributeValue &value);
mathieu@2584
    98
  
mathieu@2584
    99
  /**
mathieu@2584
   100
   * \param name the name of the global value
mathieu@2584
   101
   * \param value the value to set in the requested global value.
mathieu@2584
   102
   * \returns true if the value could be set successfully, false otherwise.
mathieu@2584
   103
   *
mathieu@2584
   104
   * Iterate over the set of GlobalValues until a matching name is found
mathieu@2584
   105
   * and then set its value with GlobalValue::SetValue.
mathieu@2584
   106
   */
mathieu@2965
   107
  static bool BindFailSafe (std::string name, const AttributeValue &value);
mathieu@2429
   108
mathieu@2584
   109
  /**
mathieu@2584
   110
   * \returns an iterator which represents a pointer to the first GlobalValue registered.
mathieu@2584
   111
   */
mathieu@2429
   112
  static Iterator Begin (void);
mathieu@2584
   113
  /**
mathieu@2584
   114
   * \returns an iterator which represents a pointer to the last GlobalValue registered.
mathieu@2584
   115
   */
mathieu@2429
   116
  static Iterator End (void);
mathieu@2429
   117
private:
mathieu@2576
   118
  friend class GlobalValueTests;
mathieu@2429
   119
  static Vector *GetVector (void);
mathieu@4214
   120
  void InitializeFromEnv (void);
mathieu@2429
   121
  std::string m_name;
mathieu@2429
   122
  std::string m_help;
mathieu@2965
   123
  Ptr<AttributeValue> m_initialValue;
mathieu@2429
   124
  Ptr<const AttributeChecker> m_checker;
mathieu@2429
   125
};
mathieu@2429
   126
mathieu@2429
   127
} // namespace ns3
mathieu@2429
   128
mathieu@2467
   129
#endif /* GLOBAL_VALUE_H */