μHAL (v2.7.9)
Part of the IPbus software repository
Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
uhal::TCP< InnerProtocol, nr_buffers_per_send > Class Template Reference

Transport protocol to transfer an IPbus buffer via TCP. More...

#include <uhal/ProtocolTCP.hpp>

Inheritance diagram for uhal::TCP< InnerProtocol, nr_buffers_per_send >:
[legend]
Collaboration diagram for uhal::TCP< InnerProtocol, nr_buffers_per_send >:
[legend]

Public Member Functions

 TCP (const std::string &aId, const URI &aUri)
 Constructor. More...
 
virtual ~TCP ()
 Destructor. More...
 

Private Types

typedef boost::chrono::steady_clock SteadyClock_t
 

Private Member Functions

 TCP (const TCP &aTCP)
 Copy Constructor This creates a new socket, dispatch queue, dispatch thread, etc. More...
 
TCPoperator= (const TCP &aTCP)
 Assignment operator This reassigns the endpoint, closes the existing socket and cleans up the buffers, etc. More...
 
void implementDispatch (boost::shared_ptr< Buffers > aBuffers)
 Send the IPbus buffer to the target, read back the response and call the packing-protocol's validate function. More...
 
virtual void Flush ()
 Concrete implementation of the synchronization function to block until all buffers have been sent, all replies received and all data validated. More...
 
virtual void dispatchExceptionHandler ()
 Function which tidies up this protocol layer in the event of an exception. More...
 
uint32_t getMaxSendSize ()
 Return the maximum size to be sent based on the buffer size in the target. More...
 
uint32_t getMaxReplySize ()
 Return the maximum size of reply packet based on the buffer size in the target. More...
 
void connect ()
 Make the TCP connection. More...
 
void write ()
 Initialize performing the next TCP write operation In multi-threaded mode, this runs the ASIO async write and exits In single-threaded mode, this runs the ASIO async write and blocks. More...
 
void write_callback (const boost::system::error_code &aErrorCode, std::size_t aBytesTransferred)
 Callback function which is called upon completion of the ASIO async write This, then, makes a call to read to read back the reply to what has just been sent. More...
 
void read ()
 Initialize performing the next TCP read operation In multi-threaded mode, this runs the ASIO async read and exits In single-threaded mode, this runs the ASIO async read and blocks. More...
 
void read_callback (const boost::system::error_code &aErrorCode, std::size_t aBytesTransferred)
 Callback function which is called upon completion of the ASIO async read This, then, checks the queue to see if there are more packets to be sent and if so, calls write. More...
 
void CheckDeadline ()
 Function called by the ASIO deadline timer. More...
 
void NotifyConditionalVariable (const bool &aValue)
 Function to set the value of a variable associated with a BOOST conditional-variable and then notify that conditional variable. More...
 
void WaitOnConditionalVariable ()
 Function to block a thread pending a BOOST conditional-variable and its associated regular variable. More...
 

Private Attributes

boost::asio::io_service mIOservice
 The boost::asio::io_service used to create the connections. More...
 
boost::asio::ip::tcp::socket mSocket
 A shared pointer to a boost::asio tcp socket through which the operation will be performed. More...
 
boost::asio::ip::tcp::resolver::iterator mEndpoint
 A shared pointer to a boost::asio tcp endpoint - used by the delayed (open-on-first-use) connect. More...
 
boost::asio::deadline_timer mDeadlineTimer
 The mechanism for providing the time-out. More...
 
boost::asio::io_service::work mIOserviceWork
 Needed when multi-threading to stop the boost::asio::io_service thinking it has nothing to do and so close the socket. More...
 
boost::thread mDispatchThread
 The Worker thread in Multi-threaded mode. More...
 
boost::mutex mTransportLayerMutex
 A MutEx lock used to make sure the access functions are thread safe. More...
 
std::deque< boost::shared_ptr< Buffers > > mDispatchQueue
 The list of buffers still waiting to be sent. More...
 
std::deque< std::pair< std::vector< boost::shared_ptr< Buffers > >, SteadyClock_t::time_point > > mReplyQueue
 The list of buffers still awaiting a reply. More...
 
uint32_t mPacketsInFlight
 Counter of how many writes have been sent, for which no reply has yet been received. More...
 
bool mFlushStarted
 Boolean specifying whether or not the main thread is within TCP::Flush method. Its value checked by the worker thread to know whether it should wait for more packets before sending onto the TCP socket. More...
 
boost::mutex mConditionalVariableMutex
 A mutex for use by the conditional variable. More...
 
boost::condition_variable mConditionalVariable
 A conditional variable for blocking the main thread until the variable with which it is associated is set correctly. More...
 
bool mFlushDone
 A variable associated with the conditional variable which specifies whether all packets have been sent and all replies have been received. More...
 
uint32_t mSendByteCounter
 Variable storing "number of bytes to follow" field for the TCP chunk currently being sent. More...
 
uint32_t mReplyByteCounter
 Variable used to store "number of bytes to follow" field for the next/current TCP chunk being received. More...
 
std::vector< boost::shared_ptr< Buffers > > mDispatchBuffers
 The buffers containing the payload for the send operation that's currently in progress. More...
 
std::pair< std::vector< boost::shared_ptr< Buffers > >, SteadyClock_t::time_point > mReplyBuffers
 The buffers containing the payloads for the receive operation that's currently in progress. More...
 
uhal::exception::exceptionmAsynchronousException
 A pointer to an exception object for passing exceptions from the worker thread to the main thread. More...
 
SteadyClock_t::time_point mLastSendQueued
 
SteadyClock_t::time_point mLastRecvQueued
 
TimeIntervalStats mRTTStats
 
TimeIntervalStats mLSTStats
 
TimeIntervalStats mInterSendTimeStats
 
TimeIntervalStats mInterRecvTimeStats
 

Detailed Description

template<typename InnerProtocol, std::size_t nr_buffers_per_send>
class uhal::TCP< InnerProtocol, nr_buffers_per_send >

Transport protocol to transfer an IPbus buffer via TCP.

Definition at line 84 of file ProtocolTCP.hpp.

Member Typedef Documentation

◆ SteadyClock_t

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
typedef boost::chrono::steady_clock uhal::TCP< InnerProtocol, nr_buffers_per_send >::SteadyClock_t
private

Definition at line 185 of file ProtocolTCP.hpp.

Constructor & Destructor Documentation

◆ TCP() [1/2]

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uhal::TCP< InnerProtocol, nr_buffers_per_send >::TCP ( const TCP< InnerProtocol, nr_buffers_per_send > &  aTCP)
private

Copy Constructor This creates a new socket, dispatch queue, dispatch thread, etc.

which connects to the same target ip/port

Parameters
aTCPa TCP-protocol object to copy

◆ TCP() [2/2]

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uhal::TCP< InnerProtocol, nr_buffers_per_send >::TCP ( const std::string &  aId,
const URI aUri 
)

Constructor.

Parameters
aIdthe unique identifier that the client will be given.
aUria struct containing the full URI of the target.

Definition at line 63 of file ProtocolTCP.cpp.

References uhal::TCP< InnerProtocol, nr_buffers_per_send >::CheckDeadline(), and uhal::TCP< InnerProtocol, nr_buffers_per_send >::mDeadlineTimer.

◆ ~TCP()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uhal::TCP< InnerProtocol, nr_buffers_per_send >::~TCP
virtual

Member Function Documentation

◆ CheckDeadline()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::CheckDeadline
private

Function called by the ASIO deadline timer.

Definition at line 528 of file ProtocolTCP.cpp.

References uhal::Debug, uhal::log(), uhal::Quote(), uhal::tests::uri, and uhal::Warning.

Referenced by uhal::TCP< InnerProtocol, nr_buffers_per_send >::TCP().

◆ connect()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::connect
private

Make the TCP connection.

Definition at line 148 of file ProtocolTCP.cpp.

References uhal::Info, uhal::log(), uhal::Quote(), and uhal::tests::uri.

◆ dispatchExceptionHandler()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::dispatchExceptionHandler
privatevirtual

Function which tidies up this protocol layer in the event of an exception.

Definition at line 581 of file ProtocolTCP.cpp.

References uhal::log(), uhal::Quote(), uhal::ClientInterface::returnBufferToPool(), uhal::tests::uri, and uhal::Warning.

◆ Flush()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::Flush
privatevirtual

Concrete implementation of the synchronization function to block until all buffers have been sent, all replies received and all data validated.

Definition at line 557 of file ProtocolTCP.cpp.

References uhal::tests::write().

◆ getMaxReplySize()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uint32_t uhal::TCP< InnerProtocol, nr_buffers_per_send >::getMaxReplySize
private

Return the maximum size of reply packet based on the buffer size in the target.

Returns
the maximum size of reply packet

Definition at line 141 of file ProtocolTCP.cpp.

◆ getMaxSendSize()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uint32_t uhal::TCP< InnerProtocol, nr_buffers_per_send >::getMaxSendSize
private

Return the maximum size to be sent based on the buffer size in the target.

Returns
the maximum size to be sent

Definition at line 134 of file ProtocolTCP.cpp.

◆ implementDispatch()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::implementDispatch ( boost::shared_ptr< Buffers aBuffers)
private

Send the IPbus buffer to the target, read back the response and call the packing-protocol's validate function.

Parameters
aBuffersthe buffer object wrapping the send and receive buffers that are to be transported If multithreaded, adds buffer to the dispatch queue and returns. If single-threaded, calls the dispatch-worker dispatch function directly and blocks until the response is validated.

Definition at line 108 of file ProtocolTCP.cpp.

References uhal::log(), uhal::Type(), and uhal::tests::write().

◆ NotifyConditionalVariable()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::NotifyConditionalVariable ( const bool &  aValue)
private

Function to set the value of a variable associated with a BOOST conditional-variable and then notify that conditional variable.

Parameters
aValuea value to which to update the variable associated with a BOOST conditional-variable

Definition at line 621 of file ProtocolTCP.cpp.

◆ operator=()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
TCP& uhal::TCP< InnerProtocol, nr_buffers_per_send >::operator= ( const TCP< InnerProtocol, nr_buffers_per_send > &  aTCP)
private

Assignment operator This reassigns the endpoint, closes the existing socket and cleans up the buffers, etc.

On the next call which requires the socket, it will be reopened with the new endpoint.

Parameters
aTCPa TCP-protocol object to copy
Returns
reference to the current object to allow chaining of assignments

◆ read()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::read
private

Initialize performing the next TCP read operation In multi-threaded mode, this runs the ASIO async read and exits In single-threaded mode, this runs the ASIO async read and blocks.

Definition at line 311 of file ProtocolTCP.cpp.

References uhal::Debug, and uhal::log().

◆ read_callback()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::read_callback ( const boost::system::error_code &  aErrorCode,
std::size_t  aBytesTransferred 
)
private

Callback function which is called upon completion of the ASIO async read This, then, checks the queue to see if there are more packets to be sent and if so, calls write.

Parameters
aErrorCodethe error code with which the ASIO operation completed

Definition at line 339 of file ProtocolTCP.cpp.

References uhal::Debug, uhal::Error, uhal::Integer(), uhal::log(), uhal::Quote(), uhal::tests::uri, uhal::ClientInterface::validate(), uhal::exception::exception::what(), and uhal::tests::write().

◆ WaitOnConditionalVariable()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::WaitOnConditionalVariable
private

Function to block a thread pending a BOOST conditional-variable and its associated regular variable.

Definition at line 631 of file ProtocolTCP.cpp.

◆ write()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::write
private

Initialize performing the next TCP write operation In multi-threaded mode, this runs the ASIO async write and exits In single-threaded mode, this runs the ASIO async write and blocks.

Definition at line 192 of file ProtocolTCP.cpp.

References uhal::Debug, uhal::Integer(), uhal::log(), and uhal::min.

◆ write_callback()

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
void uhal::TCP< InnerProtocol, nr_buffers_per_send >::write_callback ( const boost::system::error_code &  aErrorCode,
std::size_t  aBytesTransferred 
)
private

Callback function which is called upon completion of the ASIO async write This, then, makes a call to read to read back the reply to what has just been sent.

Parameters
aErrorCodethe error code with which the ASIO operation completed

Definition at line 235 of file ProtocolTCP.cpp.

References uhal::Integer(), uhal::log(), uhal::Quote(), uhal::tests::uri, and uhal::tests::write().

Member Data Documentation

◆ mAsynchronousException

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uhal::exception::exception* uhal::TCP< InnerProtocol, nr_buffers_per_send >::mAsynchronousException
private

A pointer to an exception object for passing exceptions from the worker thread to the main thread.

Exceptions must always be created on the heap (i.e. using new) and deletion will be handled in the main thread

Definition at line 257 of file ProtocolTCP.hpp.

◆ mConditionalVariable

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::condition_variable uhal::TCP< InnerProtocol, nr_buffers_per_send >::mConditionalVariable
private

A conditional variable for blocking the main thread until the variable with which it is associated is set correctly.

Definition at line 222 of file ProtocolTCP.hpp.

◆ mConditionalVariableMutex

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::mutex uhal::TCP< InnerProtocol, nr_buffers_per_send >::mConditionalVariableMutex
private

A mutex for use by the conditional variable.

Definition at line 220 of file ProtocolTCP.hpp.

◆ mDeadlineTimer

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::asio::deadline_timer uhal::TCP< InnerProtocol, nr_buffers_per_send >::mDeadlineTimer
private

The mechanism for providing the time-out.

Definition at line 197 of file ProtocolTCP.hpp.

Referenced by uhal::TCP< InnerProtocol, nr_buffers_per_send >::TCP().

◆ mDispatchBuffers

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
std::vector< boost::shared_ptr< Buffers > > uhal::TCP< InnerProtocol, nr_buffers_per_send >::mDispatchBuffers
private

The buffers containing the payload for the send operation that's currently in progress.

Note
When communicating with the ControlHub it is more efficient to send as much data as possible - i.e. multiple IPbus packets - to minimise the number of TCP chunks that are unpacked at each end of the TCP connection.

Definition at line 245 of file ProtocolTCP.hpp.

◆ mDispatchQueue

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
std::deque< boost::shared_ptr< Buffers > > uhal::TCP< InnerProtocol, nr_buffers_per_send >::mDispatchQueue
private

The list of buffers still waiting to be sent.

Definition at line 209 of file ProtocolTCP.hpp.

◆ mDispatchThread

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::thread uhal::TCP< InnerProtocol, nr_buffers_per_send >::mDispatchThread
private

The Worker thread in Multi-threaded mode.

Definition at line 203 of file ProtocolTCP.hpp.

◆ mEndpoint

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::asio::ip::tcp::resolver::iterator uhal::TCP< InnerProtocol, nr_buffers_per_send >::mEndpoint
private

A shared pointer to a boost::asio tcp endpoint - used by the delayed (open-on-first-use) connect.

Definition at line 194 of file ProtocolTCP.hpp.

◆ mFlushDone

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
bool uhal::TCP< InnerProtocol, nr_buffers_per_send >::mFlushDone
private

A variable associated with the conditional variable which specifies whether all packets have been sent and all replies have been received.

Definition at line 224 of file ProtocolTCP.hpp.

◆ mFlushStarted

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
bool uhal::TCP< InnerProtocol, nr_buffers_per_send >::mFlushStarted
private

Boolean specifying whether or not the main thread is within TCP::Flush method. Its value checked by the worker thread to know whether it should wait for more packets before sending onto the TCP socket.

Definition at line 217 of file ProtocolTCP.hpp.

◆ mInterRecvTimeStats

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
TimeIntervalStats uhal::TCP< InnerProtocol, nr_buffers_per_send >::mInterRecvTimeStats
private

Definition at line 266 of file ProtocolTCP.hpp.

◆ mInterSendTimeStats

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
TimeIntervalStats uhal::TCP< InnerProtocol, nr_buffers_per_send >::mInterSendTimeStats
private

Definition at line 265 of file ProtocolTCP.hpp.

◆ mIOservice

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::asio::io_service uhal::TCP< InnerProtocol, nr_buffers_per_send >::mIOservice
private

The boost::asio::io_service used to create the connections.

Definition at line 188 of file ProtocolTCP.hpp.

◆ mIOserviceWork

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::asio::io_service::work uhal::TCP< InnerProtocol, nr_buffers_per_send >::mIOserviceWork
private

Needed when multi-threading to stop the boost::asio::io_service thinking it has nothing to do and so close the socket.

Definition at line 200 of file ProtocolTCP.hpp.

◆ mLastRecvQueued

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
SteadyClock_t::time_point uhal::TCP< InnerProtocol, nr_buffers_per_send >::mLastRecvQueued
private

Definition at line 261 of file ProtocolTCP.hpp.

◆ mLastSendQueued

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
SteadyClock_t::time_point uhal::TCP< InnerProtocol, nr_buffers_per_send >::mLastSendQueued
private

Definition at line 260 of file ProtocolTCP.hpp.

◆ mLSTStats

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
TimeIntervalStats uhal::TCP< InnerProtocol, nr_buffers_per_send >::mLSTStats
private

Definition at line 264 of file ProtocolTCP.hpp.

◆ mPacketsInFlight

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uint32_t uhal::TCP< InnerProtocol, nr_buffers_per_send >::mPacketsInFlight
private

Counter of how many writes have been sent, for which no reply has yet been received.

Definition at line 214 of file ProtocolTCP.hpp.

◆ mReplyBuffers

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
std::pair< std::vector< boost::shared_ptr< Buffers > >, SteadyClock_t::time_point > uhal::TCP< InnerProtocol, nr_buffers_per_send >::mReplyBuffers
private

The buffers containing the payloads for the receive operation that's currently in progress.

Note
When communicating with the ControlHub it is more efficient to send as much data as possible - i.e. multiple IPbus packets - to minimise the number of TCP chunks that are unpacked at each end of the TCP connection.

Definition at line 251 of file ProtocolTCP.hpp.

◆ mReplyByteCounter

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uint32_t uhal::TCP< InnerProtocol, nr_buffers_per_send >::mReplyByteCounter
private

Variable used to store "number of bytes to follow" field for the next/current TCP chunk being received.

Note
Having this field in the TCP stream increases the efficiency (specifically, throughput) of receiving data, since uHAL can wait for the whole chunk to arrive before unpacking it.
I.e. with this field in the TCP stream, uHAL can handle more data in each TCP receive call, and therefore doesn't have to call the TCP receive function so often.

Definition at line 239 of file ProtocolTCP.hpp.

◆ mReplyQueue

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
std::deque< std::pair<std::vector< boost::shared_ptr< Buffers > >, SteadyClock_t::time_point> > uhal::TCP< InnerProtocol, nr_buffers_per_send >::mReplyQueue
private

The list of buffers still awaiting a reply.

Definition at line 211 of file ProtocolTCP.hpp.

◆ mRTTStats

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
TimeIntervalStats uhal::TCP< InnerProtocol, nr_buffers_per_send >::mRTTStats
private

Definition at line 263 of file ProtocolTCP.hpp.

◆ mSendByteCounter

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
uint32_t uhal::TCP< InnerProtocol, nr_buffers_per_send >::mSendByteCounter
private

Variable storing "number of bytes to follow" field for the TCP chunk currently being sent.

Note
Having this field in the TCP stream increases the efficiency (specifically, throughput) of sending data over the TCP stream, since the server application can wait for the whole chunk to arrive before unpacking it.
I.e. with this field in the TCP stream, the server (e.g. ControlHub) can handle more data in each TCP receive call, and therefore doesn't have to call TCP receive function so often.
Similarly uHAL handles more data in each TCP send call, and therefore doesn't have to call the TCP send function so often.

Definition at line 232 of file ProtocolTCP.hpp.

◆ mSocket

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::asio::ip::tcp::socket uhal::TCP< InnerProtocol, nr_buffers_per_send >::mSocket
private

A shared pointer to a boost::asio tcp socket through which the operation will be performed.

Definition at line 191 of file ProtocolTCP.hpp.

◆ mTransportLayerMutex

template<typename InnerProtocol , std::size_t nr_buffers_per_send>
boost::mutex uhal::TCP< InnerProtocol, nr_buffers_per_send >::mTransportLayerMutex
private

A MutEx lock used to make sure the access functions are thread safe.

Definition at line 206 of file ProtocolTCP.hpp.


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