A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
mpi-interface.h
Go to the documentation of this file.
1/*
2 * Copyright 2013. Lawrence Livermore National Security, LLC.
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Steven Smith <smith84@llnl.gov>
7 */
8
9/**
10 * \file
11 * \ingroup mpi
12 * Declaration of class ns3::MpiInterface.
13 */
14
15#ifndef NS3_MPI_INTERFACE_H
16#define NS3_MPI_INTERFACE_H
17
18#include <ns3/nstime.h>
19#include <ns3/packet.h>
20
21#include <mpi.h>
22
23namespace ns3
24{
25/**
26 * \defgroup mpi MPI Distributed Simulation
27 */
28
29/**
30 * \ingroup mpi
31 * \ingroup tests
32 * \defgroup mpi-tests MPI Distributed Simulation tests
33 */
34
35class ParallelCommunicationInterface;
36
37/**
38 * \ingroup mpi
39 *
40 * \brief Singleton used to interface to the communications infrastructure
41 * when running NS3 in parallel.
42 *
43 * Delegates the implementation to the specific parallel
44 * infrastructure being used. Implementation is defined in the
45 * ParallelCommunicationInterface virtual base class; this API mirrors
46 * that interface. This singleton is responsible for instantiating an
47 * instance of the communication interface based on
48 * SimulatorImplementationType attribute in ns3::GlobalValues. The
49 * attribute must be set before Enable is invoked.
50 */
52{
53 public:
54 /**
55 * \brief Deletes storage used by the parallel environment.
56 */
57 static void Destroy();
58 /**
59 * \brief Get the id number of this rank.
60 *
61 * When running a sequential simulation this will return a systemID of 0.
62 *
63 * \return system identification
64 */
65 static uint32_t GetSystemId();
66 /**
67 * \brief Get the number of ranks used by ns-3.
68 *
69 * Returns the size (number of MPI ranks) of the communicator used by
70 * ns-3. When running a sequential simulation this will return a
71 * size of 1.
72 *
73 * \return number of parallel tasks
74 */
75 static uint32_t GetSize();
76 /**
77 * \brief Returns enabled state of parallel environment.
78 *
79 * \return true if parallel communication is enabled
80 */
81 static bool IsEnabled();
82 /**
83 * \brief Setup the parallel communication interface.
84 *
85 * There are two ways to setup the communications interface. This
86 * Enable method is the easiest method and should be used in most
87 * situations.
88 *
89 * Disable() must be invoked at end of an ns-3 application to
90 * properly cleanup the parallel communication interface.
91 *
92 * This method will call MPI_Init and configure ns-3 to use the
93 * MPI_COMM_WORLD communicator.
94 *
95 * For more complex situations, such as embedding ns-3 with other
96 * MPI simulators or libraries, the Enable(MPI_Comm communcicator)
97 * may be used if MPI is initialized externally or if ns-3 needs to
98 * be run unique communicator. For example if there are two
99 * parallel simulators and the goal is to run each simulator on a
100 * different set of ranks.
101 *
102 * \note The `SimulatorImplementationType attribute in
103 * ns3::GlobalValues must be set before calling Enable()
104 *
105 * \param pargc number of command line arguments
106 * \param pargv command line arguments
107 */
108 static void Enable(int* pargc, char*** pargv);
109 /**
110 * \brief Setup the parallel communication interface using the specified communicator.
111 *
112 * See @ref Enable (int* pargc, char*** pargv) for additional information.
113 *
114 * \param communicator MPI Communicator that should be used by ns-3
115 */
116 static void Enable(MPI_Comm communicator);
117 /**
118 * \brief Clean up the ns-3 parallel communications interface.
119 *
120 * MPI_Finalize will be called only if Enable (int* pargc, char***
121 * pargv) was called.
122 */
123 static void Disable();
124 /**
125 * \brief Send a packet to a remote node.
126 *
127 * \param p packet to send
128 * \param rxTime received time at destination node
129 * \param node destination node
130 * \param dev destination device
131 *
132 * Serialize and send a packet to the specified node and net device
133 */
134 static void SendPacket(Ptr<Packet> p, const Time& rxTime, uint32_t node, uint32_t dev);
135
136 /**
137 * \brief Return the communicator used to run ns-3.
138 *
139 * The communicator returned will be MPI_COMM_WORLD if Enable (int*
140 * pargc, char*** pargv) is used to enable or the user specified
141 * communicator if Enable (MPI_Comm communicator) is used.
142 *
143 * \return The MPI Communicator.
144 */
145 static MPI_Comm GetCommunicator();
146
147 private:
148 /**
149 * Common enable logic.
150 */
151 static void SetParallelSimulatorImpl();
152
153 /**
154 * Static instance of the instantiated parallel controller.
155 */
157};
158
159} // namespace ns3
160
161#endif /* NS3_MPI_INTERFACE_H */
Singleton used to interface to the communications infrastructure when running NS3 in parallel.
static ParallelCommunicationInterface * g_parallelCommunicationInterface
Static instance of the instantiated parallel controller.
static MPI_Comm GetCommunicator()
Return the communicator used to run ns-3.
static void SendPacket(Ptr< Packet > p, const Time &rxTime, uint32_t node, uint32_t dev)
Send a packet to a remote node.
static bool IsEnabled()
Returns enabled state of parallel environment.
static void Destroy()
Deletes storage used by the parallel environment.
static uint32_t GetSystemId()
Get the id number of this rank.
static uint32_t GetSize()
Get the number of ranks used by ns-3.
static void Disable()
Clean up the ns-3 parallel communications interface.
static void Enable(int *pargc, char ***pargv)
Setup the parallel communication interface.
static void SetParallelSimulatorImpl()
Common enable logic.
Pure virtual base class for the interface between ns-3 and the parallel communication layer being use...
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Every class exported by the ns3 library is enclosed in the ns3 namespace.