A Discrete-Event Network Simulator
API
ns3::MpiInterface Class Reference

Singleton used to interface to the communications infrastructure when running NS3 in parallel. More...

#include "mpi-interface.h"

+ Collaboration diagram for ns3::MpiInterface:

Static Public Member Functions

static void Destroy ()
 Deletes storage used by the parallel environment. More...
 
static void Disable ()
 Clean up the ns-3 parallel communications interface. More...
 
static void Enable (int *pargc, char ***pargv)
 Setup the parallel communication interface. More...
 
static void Enable (MPI_Comm communicator)
 Setup the parallel communication interface using the specified communicator. More...
 
static MPI_Comm GetCommunicator ()
 Return the communicator used to run ns-3. More...
 
static uint32_t GetSize ()
 Get the number of ranks used by ns-3. More...
 
static uint32_t GetSystemId ()
 Get the id number of this rank. More...
 
static bool IsEnabled ()
 Returns enabled state of parallel environment. More...
 
static void SendPacket (Ptr< Packet > p, const Time &rxTime, uint32_t node, uint32_t dev)
 Send a packet to a remote node. More...
 

Static Private Member Functions

static void SetParallelSimulatorImpl (void)
 Common enable logic. More...
 

Static Private Attributes

static ParallelCommunicationInterfaceg_parallelCommunicationInterface = 0
 Static instance of the instantiated parallel controller. More...
 

Detailed Description

Singleton used to interface to the communications infrastructure when running NS3 in parallel.


Delegates the implementation to the specific parallel infrastructure being used. Implementation is defined in the ParallelCommunicationInterface virtual base class; this API mirrors that interface. This singleton is responsible for instantiating an instance of the communication interface based on SimulatorImplementationType attribute in ns3::GlobalValues. The attribute must be set before Enable is invoked.

Definition at line 62 of file mpi-interface.h.

Member Function Documentation

◆ Destroy()

void ns3::MpiInterface::Destroy ( void  )
static

Deletes storage used by the parallel environment.

Definition at line 43 of file mpi-interface.cc.

References ns3::ParallelCommunicationInterface::Destroy(), g_parallelCommunicationInterface, and NS_ASSERT.

Referenced by ns3::DistributedSimulatorImpl::Destroy(), and ns3::NullMessageSimulatorImpl::Destroy().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Disable()

void ns3::MpiInterface::Disable ( )
static

Clean up the ns-3 parallel communications interface.

MPI_Finalize will be called only if Enable (int* pargc, char*** pargv) was called.

Definition at line 146 of file mpi-interface.cc.

References ns3::ParallelCommunicationInterface::Disable(), g_parallelCommunicationInterface, and NS_ASSERT.

+ Here is the call graph for this function:

◆ Enable() [1/2]

void ns3::MpiInterface::Enable ( int *  pargc,
char ***  pargv 
)
static

Setup the parallel communication interface.

There are two ways to setup the communications interface. This Enable method is the easiest method and should be used in most situations.

Disable() must be invoked at end of an ns-3 application to properly cleanup the parallel communication interface.

This method will call MPI_Init and configure ns-3 to use the MPI_COMM_WORLD communicator.

For more complex situations, such as embedding ns-3 with other MPI simulators or libraries, the Enable(MPI_Comm communcicator) may be used if MPI is initialized externally or if ns-3 needs to be run unique communicator. For example if there are two parallel simulators and the goal is to run each simulator on a different set of ranks.

Note
The `SimulatorImplementationType attribute in ns3::GlobalValues must be set before calling Enable()
Parameters
pargcnumber of command line arguments
pargvcommand line arguments

Definition at line 115 of file mpi-interface.cc.

References ns3::ParallelCommunicationInterface::Enable(), g_parallelCommunicationInterface, and SetParallelSimulatorImpl().

+ Here is the call graph for this function:

◆ Enable() [2/2]

void ns3::MpiInterface::Enable ( MPI_Comm  communicator)
static

Setup the parallel communication interface using the specified communicator.

See Enable (int* pargc, char*** pargv) for additional information.

Parameters
communicatorMPI Communicator that should be used by ns-3

Definition at line 124 of file mpi-interface.cc.

References ns3::ParallelCommunicationInterface::Enable(), g_parallelCommunicationInterface, and SetParallelSimulatorImpl().

+ Here is the call graph for this function:

◆ GetCommunicator()

MPI_Comm ns3::MpiInterface::GetCommunicator ( )
static

Return the communicator used to run ns-3.

The communicator returned will be MPI_COMM_WORLD if Enable (int* pargc, char*** pargv) is used to enable or the user specified communicator if Enable (MPI_Comm communicator) is used.

Returns
The MPI Communicator.

Definition at line 138 of file mpi-interface.cc.

References g_parallelCommunicationInterface, ns3::ParallelCommunicationInterface::GetCommunicator(), and NS_ASSERT.

Referenced by ns3::DistributedSimulatorImpl::CalculateLookAhead(), and ns3::DistributedSimulatorImpl::Run().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetSize()

uint32_t ns3::MpiInterface::GetSize ( void  )
static

Get the number of ranks used by ns-3.

Returns the size (number of MPI ranks) of the communicator used by ns-3. When running a sequential simulation this will return a size of 1.

Returns
number of parallel tasks

Definition at line 59 of file mpi-interface.cc.

References g_parallelCommunicationInterface, and ns3::ParallelCommunicationInterface::GetSize().

Referenced by ns3::DistributedSimulatorImpl::DistributedSimulatorImpl(), ns3::NullMessageSimulatorImpl::NullMessageSimulatorImpl(), ns3::DistributedSimulatorImpl::CalculateLookAhead(), ns3::NullMessageSimulatorImpl::CalculateLookAhead(), and ns3::GrantedTimeWindowMpiInterface::ReceiveMessages().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetSystemId()

uint32_t ns3::MpiInterface::GetSystemId ( void  )
static

Get the id number of this rank.

When running a sequential simulation this will return a systemID of 0.

Returns
system identification

Definition at line 50 of file mpi-interface.cc.

References g_parallelCommunicationInterface, and ns3::ParallelCommunicationInterface::GetSystemId().

Referenced by ns3::DistributedSimulatorImpl::DistributedSimulatorImpl(), ns3::NullMessageSimulatorImpl::NullMessageSimulatorImpl(), ns3::DistributedSimulatorImpl::CalculateLookAhead(), ns3::NullMessageSimulatorImpl::CalculateLookAhead(), and ns3::PointToPointHelper::Install().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsEnabled()

bool ns3::MpiInterface::IsEnabled ( )
static

Returns enabled state of parallel environment.

Returns
true if parallel communication is enabled

Definition at line 68 of file mpi-interface.cc.

References g_parallelCommunicationInterface, and ns3::ParallelCommunicationInterface::IsEnabled().

Referenced by ns3::PointToPointHelper::Install().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ SendPacket()

void ns3::MpiInterface::SendPacket ( Ptr< Packet p,
const Time rxTime,
uint32_t  node,
uint32_t  dev 
)
static

Send a packet to a remote node.

Parameters
ppacket to send
rxTimereceived time at destination node
nodedestination node
devdestination device

Serialize and send a packet to the specified node and net device

Definition at line 131 of file mpi-interface.cc.

References g_parallelCommunicationInterface, NS_ASSERT, and ns3::ParallelCommunicationInterface::SendPacket().

Referenced by ns3::PointToPointRemoteChannel::TransmitStart().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ SetParallelSimulatorImpl()

void ns3::MpiInterface::SetParallelSimulatorImpl ( void  )
staticprivate

Common enable logic.

Definition at line 81 of file mpi-interface.cc.

References ns3::GlobalValue::Bind(), g_parallelCommunicationInterface, ns3::StringValue::Get(), ns3::GlobalValue::GetValueByNameFailSafe(), and NS_LOG_WARN.

Referenced by Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Member Data Documentation

◆ g_parallelCommunicationInterface

ParallelCommunicationInterface * ns3::MpiInterface::g_parallelCommunicationInterface = 0
staticprivate

Static instance of the instantiated parallel controller.

Definition at line 168 of file mpi-interface.h.

Referenced by Destroy(), Disable(), Enable(), GetCommunicator(), GetSize(), GetSystemId(), IsEnabled(), SendPacket(), and SetParallelSimulatorImpl().


The documentation for this class was generated from the following files: