A Discrete-Event Network Simulator
API
ns3::FdReader Class Referenceabstract

A class that asynchronously reads from a file descriptor. More...

#include "fd-reader.h"

+ Inheritance diagram for ns3::FdReader:
+ Collaboration diagram for ns3::FdReader:

Classes

struct  Data
 A structure representing data read. More...
 

Public Member Functions

 FdReader ()
 Constructor. More...
 
virtual ~FdReader ()
 Destructor. More...
 
void Start (int fd, Callback< void, uint8_t *, ssize_t > readCallback)
 Start a new read thread. More...
 
void Stop ()
 Stop the read thread and reset internal state. More...
 
- Public Member Functions inherited from ns3::SimpleRefCount< FdReader >
 SimpleRefCount ()
 Default constructor. More...
 
 SimpleRefCount (const SimpleRefCount &o[[maybe_unused]])
 Copy constructor. More...
 
uint32_t GetReferenceCount () const
 Get the reference count of the object. More...
 
SimpleRefCountoperator= (const SimpleRefCount &o[[maybe_unused]])
 Assignment operator. More...
 
void Ref () const
 Increment the reference count. More...
 
void Unref () const
 Decrement the reference count. More...
 

Protected Member Functions

virtual FdReader::Data DoRead ()=0
 The read implementation. More...
 

Protected Attributes

int m_fd
 The file descriptor to read from. More...
 

Private Member Functions

void DestroyEvent ()
 Event handler scheduled for destroy time to halt the thread. More...
 
void Run ()
 The asynchronous function which performs the read. More...
 

Private Attributes

EventId m_destroyEvent
 The event scheduled for destroy time which will invoke DestroyEvent and halt the thread. More...
 
int m_evpipe [2]
 Pipe used to signal events between threads. More...
 
Callback< void, uint8_t *, ssize_t > m_readCallback
 The main thread callback function to invoke when we have data. More...
 
std::thread m_readThread
 The thread doing the read, created and launched by Start(). More...
 
bool m_stop
 Signal the read thread to stop. More...
 

Detailed Description

A class that asynchronously reads from a file descriptor.

This class can be used to start a system thread that reads from a given file descriptor and invokes a given callback when data is received. This class handles thread management automatically but the DoRead() method must be implemented by a subclass.

Definition at line 56 of file fd-reader.h.

Constructor & Destructor Documentation

◆ FdReader()

ns3::FdReader::FdReader ( )

Constructor.

Definition at line 45 of file unix-fd-reader.cc.

References m_evpipe, and NS_LOG_FUNCTION.

◆ ~FdReader()

ns3::FdReader::~FdReader ( )
virtual

Destructor.

Definition at line 55 of file unix-fd-reader.cc.

References NS_LOG_FUNCTION, and Stop().

+ Here is the call graph for this function:

Member Function Documentation

◆ DestroyEvent()

void ns3::FdReader::DestroyEvent ( )
private

Event handler scheduled for destroy time to halt the thread.

Definition at line 113 of file unix-fd-reader.cc.

References NS_LOG_FUNCTION, Stop(), and ns3::SimpleRefCount< FdReader >::Unref().

Referenced by Start().

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

◆ DoRead()

virtual FdReader::Data ns3::FdReader::DoRead ( )
protectedpure virtual

The read implementation.

The value of m_len returned controls further processing. The callback function is only invoked when m_len is positive; any data read is not processed when m_len is negative; reading stops when m_len is zero.

The management of memory associated with m_buf must be compatible with the read callback.

Returns
A structure representing what was read.

Implemented in ns3::TapBridgeFdReader, ns3::FdNetDeviceFdReader, and ns3::NetmapNetDeviceFdReader.

Referenced by Run().

+ Here is the caller graph for this function:

◆ Run()

void ns3::FdReader::Run ( )
private

The asynchronous function which performs the read.

Definition at line 165 of file unix-fd-reader.cc.

References data, DoRead(), m_evpipe, m_fd, m_readCallback, m_stop, NS_FATAL_ERROR, and NS_LOG_FUNCTION.

Referenced by Start().

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

◆ Start()

void ns3::FdReader::Start ( int  fd,
Callback< void, uint8_t *, ssize_t >  readCallback 
)

Start a new read thread.

Parameters
[in]fdA valid file descriptor open for reading.
[in]readCallbackA callback to invoke when new data is available.

Definition at line 62 of file unix-fd-reader.cc.

References DestroyEvent(), ns3::EventId::IsRunning(), m_destroyEvent, m_evpipe, m_fd, m_readCallback, m_readThread, NS_ASSERT_MSG, NS_FATAL_ERROR, NS_LOG_FUNCTION, NS_LOG_LOGIC, ns3::SimpleRefCount< FdReader >::Ref(), Run(), and ns3::Simulator::ScheduleDestroy().

+ Here is the call graph for this function:

◆ Stop()

void ns3::FdReader::Stop ( )

Stop the read thread and reset internal state.

This does not close the file descriptor used for reading.

Definition at line 121 of file unix-fd-reader.cc.

References m_evpipe, m_fd, m_readCallback, m_readThread, m_stop, NS_LOG_FUNCTION, NS_LOG_WARN, ns3::Callback< R, UArgs >::Nullify(), and zero.

Referenced by ~FdReader(), and DestroyEvent().

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

Member Data Documentation

◆ m_destroyEvent

EventId ns3::FdReader::m_destroyEvent
private

The event scheduled for destroy time which will invoke DestroyEvent and halt the thread.

Definition at line 158 of file fd-reader.h.

Referenced by Start().

◆ m_evpipe

int ns3::FdReader::m_evpipe[2]
private

Pipe used to signal events between threads.

Definition at line 150 of file fd-reader.h.

Referenced by FdReader(), Run(), Start(), and Stop().

◆ m_fd

int ns3::FdReader::m_fd
protected

The file descriptor to read from.

Definition at line 135 of file fd-reader.h.

Referenced by ns3::NetmapNetDeviceFdReader::DoRead(), ns3::FdNetDeviceFdReader::DoRead(), ns3::TapBridgeFdReader::DoRead(), Run(), Start(), and Stop().

◆ m_readCallback

Callback<void, uint8_t*, ssize_t> ns3::FdReader::m_readCallback
private

The main thread callback function to invoke when we have data.

Definition at line 144 of file fd-reader.h.

Referenced by Run(), Start(), and Stop().

◆ m_readThread

std::thread ns3::FdReader::m_readThread
private

The thread doing the read, created and launched by Start().

Definition at line 147 of file fd-reader.h.

Referenced by Start(), and Stop().

◆ m_stop

bool ns3::FdReader::m_stop
private

Signal the read thread to stop.

Definition at line 152 of file fd-reader.h.

Referenced by Run(), and Stop().


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