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

Interface between ns-3 and MPI for the Null Message distributed simulation implementation. More...

#include "null-message-mpi-interface.h"

+ Inheritance diagram for ns3::NullMessageMpiInterface:
+ Collaboration diagram for ns3::NullMessageMpiInterface:

Public Member Functions

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

Static Public Member Functions

static TypeId GetTypeId (void)
 Register this type. More...
 

Static Private Member Functions

static void InitializeSendReceiveBuffers (void)
 Initialize send and receive buffers. More...
 
static void ReceiveMessages (bool blocking=false)
 Check for received messages complete. More...
 
static void ReceiveMessagesBlocking ()
 Blocking message receive. More...
 
static void ReceiveMessagesNonBlocking ()
 Non-blocking check for received messages complete. More...
 
static void SendNullMessage (const Time &guaranteeUpdate, Ptr< RemoteChannelBundle > bundle)
 Send a Null Message to across the specified bundle. More...
 
static void TestSendComplete ()
 Check for completed sends. More...
 
- Static Private Member Functions inherited from ns3::Object
static TypeId GetTypeId (void)
 Register this type. More...
 
- Static Private Member Functions inherited from ns3::ObjectBase
static TypeId GetTypeId (void)
 Get the type ID. More...
 

Static Private Attributes

static MPI_Comm g_communicator = MPI_COMM_WORLD
 MPI communicator being used for ns-3 tasks. More...
 
static bool g_enabled = false
 Has this interface been enabled. More...
 
static bool g_freeCommunicator = false
 Did we create the communicator? Have to free it. More...
 
static bool g_mpiInitCalled = false
 Has MPI Init been called by this interface. More...
 
static uint32_t g_numNeighbors = 0
 Number of neighbor tasks, tasks that this task shares a link with. More...
 
static std::list< NullMessageSentBufferg_pendingTx
 List of pending non-blocking sends. More...
 
static char ** g_pRxBuffers
 Data buffers for non-blocking receives. More...
 
static MPI_Request * g_requests
 Pending non-blocking receives. More...
 
static uint32_t g_sid = 0
 System ID (rank) for this task. More...
 
static uint32_t g_size = 1
 Size of the MPI COM_WORLD group. More...
 

Additional Inherited Members

- Private Member Functions inherited from ns3::Object
 Object ()
 Constructor. More...
 
virtual ~Object ()
 Destructor. More...
 
void AggregateObject (Ptr< Object > other)
 Aggregate two Objects together. More...
 
void Dispose (void)
 Dispose of this Object. More...
 
AggregateIterator GetAggregateIterator (void) const
 Get an iterator to the Objects aggregated to this one. More...
 
virtual TypeId GetInstanceTypeId (void) const
 Get the most derived TypeId for this Object. More...
 
template<>
Ptr< ObjectGetObject () const
 Specialization of () for objects of type ns3::Object. More...
 
template<typename T >
Ptr< T > GetObject (TypeId tid) const
 Get a pointer to the requested aggregated Object by TypeId. More...
 
template<>
Ptr< ObjectGetObject (TypeId tid) const
 Specialization of (TypeId tid) for objects of type ns3::Object. More...
 
template<typename T >
Ptr< T > GetObject (void) const
 Get a pointer to the requested aggregated Object. More...
 
void Initialize (void)
 Invoke DoInitialize on all Objects aggregated to this one. More...
 
bool IsInitialized (void) const
 Check if the object has been initialized. More...
 
 Object (const Object &o)
 Copy an Object. More...
 
virtual void DoDispose (void)
 Destructor implementation. More...
 
virtual void DoInitialize (void)
 Initialize() implementation. More...
 
virtual void NotifyNewAggregate (void)
 Notify all Objects aggregated to this one of a new Object being aggregated. More...
 
- Private Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
 SimpleRefCount ()
 Default constructor. More...
 
 SimpleRefCount (const SimpleRefCount &o[[maybe_unused]])
 Copy constructor. More...
 
uint32_t GetReferenceCount (void) const
 Get the reference count of the object. More...
 
SimpleRefCountoperator= ([[maybe_unused]] const SimpleRefCount &o)
 Assignment operator. More...
 
void Ref (void) const
 Increment the reference count. More...
 
void Unref (void) const
 Decrement the reference count. More...
 
- Private Member Functions inherited from ns3::ObjectBase
virtual ~ObjectBase ()
 Virtual destructor. More...
 
void GetAttribute (std::string name, AttributeValue &value) const
 Get the value of an attribute, raising fatal errors if unsuccessful. More...
 
bool GetAttributeFailSafe (std::string name, AttributeValue &value) const
 Get the value of an attribute without raising erros. More...
 
void SetAttribute (std::string name, const AttributeValue &value)
 Set a single attribute, raising fatal errors if unsuccessful. More...
 
bool SetAttributeFailSafe (std::string name, const AttributeValue &value)
 Set a single attribute without raising errors. More...
 
bool TraceConnect (std::string name, std::string context, const CallbackBase &cb)
 Connect a TraceSource to a Callback with a context. More...
 
bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb)
 Connect a TraceSource to a Callback without a context. More...
 
bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected with a context. More...
 
bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected without a context. More...
 
void ConstructSelf (const AttributeConstructionList &attributes)
 Complete construction of ObjectBase; invoked by derived classes. More...
 
virtual void NotifyConstructionCompleted (void)
 Notifier called once the ObjectBase is fully constructed. More...
 

Detailed Description

Interface between ns-3 and MPI for the Null Message distributed simulation implementation.

Definition at line 51 of file null-message-mpi-interface.h.

Constructor & Destructor Documentation

◆ NullMessageMpiInterface()

ns3::NullMessageMpiInterface::NullMessageMpiInterface ( )

Definition at line 151 of file null-message-mpi-interface.cc.

References NS_LOG_FUNCTION.

◆ ~NullMessageMpiInterface()

ns3::NullMessageMpiInterface::~NullMessageMpiInterface ( )

Definition at line 156 of file null-message-mpi-interface.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

◆ Destroy()

void ns3::NullMessageMpiInterface::Destroy ( )
virtual

Deletes storage used by the parallel environment.

Implements ns3::ParallelCommunicationInterface.

Definition at line 162 of file null-message-mpi-interface.cc.

References NS_LOG_FUNCTION.

◆ Disable()

void ns3::NullMessageMpiInterface::Disable ( )
virtual

Clean up the ns-3 parallel communications interface.

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

Implements ns3::ParallelCommunicationInterface.

Definition at line 465 of file null-message-mpi-interface.cc.

References g_communicator, g_enabled, g_freeCommunicator, g_mpiInitCalled, g_numNeighbors, g_pendingTx, g_pRxBuffers, g_requests, NS_FATAL_ERROR, and NS_LOG_FUNCTION.

◆ Enable() [1/2]

void ns3::NullMessageMpiInterface::Enable ( int *  pargc,
char ***  pargv 
)
virtual

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

Implements ns3::ParallelCommunicationInterface.

Definition at line 195 of file null-message-mpi-interface.cc.

References g_enabled, g_mpiInitCalled, NS_ASSERT, and NS_LOG_FUNCTION.

◆ Enable() [2/2]

void ns3::NullMessageMpiInterface::Enable ( MPI_Comm  communicator)
virtual

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

Implements ns3::ParallelCommunicationInterface.

Definition at line 208 of file null-message-mpi-interface.cc.

References g_communicator, g_enabled, g_freeCommunicator, g_sid, g_size, NS_ASSERT, and NS_LOG_FUNCTION.

◆ GetCommunicator()

MPI_Comm ns3::NullMessageMpiInterface::GetCommunicator ( )
virtual

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.

Implements ns3::ParallelCommunicationInterface.

Definition at line 182 of file null-message-mpi-interface.cc.

References g_communicator, g_enabled, and NS_ASSERT.

◆ GetSize()

uint32_t ns3::NullMessageMpiInterface::GetSize ( )
virtual

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

Implements ns3::ParallelCommunicationInterface.

Definition at line 175 of file null-message-mpi-interface.cc.

References g_enabled, g_size, and NS_ASSERT.

◆ GetSystemId()

uint32_t ns3::NullMessageMpiInterface::GetSystemId ( )
virtual

Get the id number of this rank.

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

Returns
system identification

Implements ns3::ParallelCommunicationInterface.

Definition at line 168 of file null-message-mpi-interface.cc.

References g_enabled, g_sid, and NS_ASSERT.

◆ GetTypeId()

TypeId ns3::NullMessageMpiInterface::GetTypeId ( void  )
static

Register this type.

Returns
The object TypeId.

Definition at line 142 of file null-message-mpi-interface.cc.

References ns3::TypeId::SetParent().

+ Here is the call graph for this function:

◆ InitializeSendReceiveBuffers()

void ns3::NullMessageMpiInterface::InitializeSendReceiveBuffers ( void  )
staticprivate

Initialize send and receive buffers.

This method should be called after all links have been added to the RemoteChannelBundle manager to setup any required send and receive buffers.

Definition at line 235 of file null-message-mpi-interface.cc.

References ns3::RemoteChannelBundleManager::Find(), g_communicator, g_enabled, g_numNeighbors, g_pRxBuffers, g_requests, g_size, NS_ASSERT, NS_LOG_FUNCTION_NOARGS, ns3::NULL_MESSAGE_MAX_MPI_MSG_SIZE, and ns3::RemoteChannelBundleManager::Size().

Referenced by ns3::NullMessageSimulatorImpl::CalculateLookAhead().

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

◆ IsEnabled()

bool ns3::NullMessageMpiInterface::IsEnabled ( )
virtual

Returns enabled state of parallel environment.

Returns
true if parallel communication is enabled

Implements ns3::ParallelCommunicationInterface.

Definition at line 189 of file null-message-mpi-interface.cc.

References g_enabled.

◆ ReceiveMessages()

void ns3::NullMessageMpiInterface::ReceiveMessages ( bool  blocking = false)
staticprivate

Check for received messages complete.

Will block until message has been received if blocking flag is true. When blocking will return after the first message is received. Non-blocking mode will only check for received messages complete, and return all messages that are queued up locally.

Parameters
[in]blockingWhether this call should block.

Definition at line 345 of file null-message-mpi-interface.cc.

References ns3::RemoteChannelBundleManager::Find(), g_communicator, g_enabled, g_numNeighbors, g_pRxBuffers, g_requests, ns3::Node::GetDevice(), ns3::Node::GetId(), ns3::NetDevice::GetIfIndex(), ns3::Node::GetNDevices(), ns3::NodeList::GetNode(), ns3::Object::GetObject(), ns3::Simulator::Now(), NS_ASSERT, NS_LOG_FUNCTION, ns3::NULL_MESSAGE_MAX_MPI_MSG_SIZE, ns3::MpiReceiver::Receive(), and ns3::Simulator::ScheduleWithContext().

Referenced by ReceiveMessagesBlocking(), and ReceiveMessagesNonBlocking().

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

◆ ReceiveMessagesBlocking()

void ns3::NullMessageMpiInterface::ReceiveMessagesBlocking ( )
staticprivate

Blocking message receive.

Will block until at least one message has been received.

Definition at line 328 of file null-message-mpi-interface.cc.

References NS_LOG_FUNCTION_NOARGS, and ReceiveMessages().

Referenced by ns3::NullMessageSimulatorImpl::HandleArrivingMessagesBlocking().

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

◆ ReceiveMessagesNonBlocking()

void ns3::NullMessageMpiInterface::ReceiveMessagesNonBlocking ( )
staticprivate

Non-blocking check for received messages complete.

Will receive all messages that are queued up locally.

Definition at line 337 of file null-message-mpi-interface.cc.

References NS_LOG_FUNCTION_NOARGS, and ReceiveMessages().

Referenced by ns3::NullMessageSimulatorImpl::HandleArrivingMessagesNonBlocking().

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

◆ SendNullMessage()

void ns3::NullMessageMpiInterface::SendNullMessage ( const Time guaranteeUpdate,
Ptr< RemoteChannelBundle bundle 
)
staticprivate

Send a Null Message to across the specified bundle.


Null Messages are sent when a packet has not been sent across this bundle in order to allow time advancement on the remote MPI task.

Parameters
[in]guaranteeUpdateLower bound time on the next possible event from this MPI task to the remote MPI task across the bundle. Remote task may execute events up to this time.
[in]bundleThe bundle of links between two ranks.
Internal: The Null Message MPI buffer format uses the same packet
metadata format as sending a normal packet with the time, destination node, and destination device set to zero. Using the same packet metadata simplifies receive logic.

Definition at line 299 of file null-message-mpi-interface.cc.

References g_communicator, g_enabled, g_pendingTx, ns3::Time::GetInteger(), ns3::Time::GetTimeStep(), NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by ns3::NullMessageSimulatorImpl::NullMessageEventHandler(), and ns3::RemoteChannelBundle::Send().

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

◆ SendPacket()

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

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

Implements ns3::ParallelCommunicationInterface.

Definition at line 260 of file null-message-mpi-interface.cc.

References ns3::NullMessageSimulatorImpl::CalculateGuaranteeTime(), g_communicator, g_enabled, g_pendingTx, ns3::NullMessageSimulatorImpl::GetInstance(), ns3::Time::GetInteger(), ns3::NodeList::GetNode(), ns3::Packet::GetSerializedSize(), ns3::Node::GetSystemId(), ns3::Time::GetTimeStep(), NS_ASSERT, NS_LOG_FUNCTION, ns3::NullMessageSimulatorImpl::RescheduleNullMessageEvent(), and ns3::Packet::Serialize().

+ Here is the call graph for this function:

◆ TestSendComplete()

void ns3::NullMessageMpiInterface::TestSendComplete ( )
staticprivate

Check for completed sends.

Definition at line 443 of file null-message-mpi-interface.cc.

References g_enabled, g_pendingTx, NS_ASSERT, and NS_LOG_FUNCTION_NOARGS.

Referenced by ns3::NullMessageSimulatorImpl::HandleArrivingMessagesBlocking(), and ns3::NullMessageSimulatorImpl::HandleArrivingMessagesNonBlocking().

+ Here is the caller graph for this function:

Member Data Documentation

◆ g_communicator

MPI_Comm ns3::NullMessageMpiInterface::g_communicator = MPI_COMM_WORLD
staticprivate

MPI communicator being used for ns-3 tasks.

Definition at line 166 of file null-message-mpi-interface.h.

Referenced by Disable(), Enable(), GetCommunicator(), InitializeSendReceiveBuffers(), ReceiveMessages(), SendNullMessage(), and SendPacket().

◆ g_enabled

bool ns3::NullMessageMpiInterface::g_enabled = false
staticprivate

◆ g_freeCommunicator

bool ns3::NullMessageMpiInterface::g_freeCommunicator = false
staticprivate

Did we create the communicator? Have to free it.

Definition at line 169 of file null-message-mpi-interface.h.

Referenced by Disable(), and Enable().

◆ g_mpiInitCalled

bool ns3::NullMessageMpiInterface::g_mpiInitCalled = false
staticprivate

Has MPI Init been called by this interface.

Alternatively user supplies a communicator.

Definition at line 154 of file null-message-mpi-interface.h.

Referenced by Disable(), and Enable().

◆ g_numNeighbors

uint32_t ns3::NullMessageMpiInterface::g_numNeighbors = 0
staticprivate

Number of neighbor tasks, tasks that this task shares a link with.

Definition at line 145 of file null-message-mpi-interface.h.

Referenced by Disable(), InitializeSendReceiveBuffers(), and ReceiveMessages().

◆ g_pendingTx

std::list< NullMessageSentBuffer > ns3::NullMessageMpiInterface::g_pendingTx
staticprivate

List of pending non-blocking sends.

Definition at line 163 of file null-message-mpi-interface.h.

Referenced by Disable(), SendNullMessage(), SendPacket(), and TestSendComplete().

◆ g_pRxBuffers

char ** ns3::NullMessageMpiInterface::g_pRxBuffers
staticprivate

Data buffers for non-blocking receives.

Definition at line 160 of file null-message-mpi-interface.h.

Referenced by Disable(), InitializeSendReceiveBuffers(), and ReceiveMessages().

◆ g_requests

MPI_Request * ns3::NullMessageMpiInterface::g_requests
staticprivate

Pending non-blocking receives.

Definition at line 157 of file null-message-mpi-interface.h.

Referenced by Disable(), InitializeSendReceiveBuffers(), and ReceiveMessages().

◆ g_sid

uint32_t ns3::NullMessageMpiInterface::g_sid = 0
staticprivate

System ID (rank) for this task.

Definition at line 139 of file null-message-mpi-interface.h.

Referenced by Enable(), and GetSystemId().

◆ g_size

uint32_t ns3::NullMessageMpiInterface::g_size = 1
staticprivate

Size of the MPI COM_WORLD group.

Definition at line 142 of file null-message-mpi-interface.h.

Referenced by Enable(), GetSize(), and InitializeSendReceiveBuffers().


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