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

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

#include <uhal/ProtocolUDP.hpp>

Inheritance diagram for uhal::UDP< InnerProtocol >:
[legend]
Collaboration diagram for uhal::UDP< InnerProtocol >:
[legend]

Public Member Functions

 UDP (const std::string &aId, const URI &aUri)
 Functor class to perform the actual transport, Like this to allow multithreading if desirable. More...
 
virtual ~UDP ()
 Destructor. More...
 

Private Member Functions

 UDP (const UDP &aUDP)
 Copy Constructor This creates a new socket, dispatch queue, dispatch thread, etc. More...
 
UDPoperator= (const UDP &aUDP)
 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 ()
 Set up the UDP socket. More...
 
void write ()
 Initialize performing the next UDP write operation In multi-threaded mode, this runs the ASIO async send and exits In single-threaded mode, this runs the ASIO async send 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 send 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 UDP read operation In multi-threaded mode, this runs the ASIO async receive and exits In single-threaded mode, this runs the ASIO async receive 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 receive 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::udp::socket mSocket
 A shared pointer to a boost::asio udp socket through which the operation will be performed. More...
 
boost::asio::ip::udp::endpoint mEndpoint
 A shared pointer to a boost::asio udp endpoint - used in the ASIO send and receive functions (UDP has no concept of a connection) More...
 
boost::asio::deadline_timer mDeadlineTimer
 The mechanism for providing the time-out. More...
 
std::vector< uint8_t > mReplyMemory
 A block of memory into which we write replies, before copying them to their final destination. 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< boost::shared_ptr< Buffers > > 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...
 
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...
 
boost::shared_ptr< BuffersmDispatchBuffers
 The send operation currently in progress. More...
 
boost::shared_ptr< BuffersmReplyBuffers
 The receive operation currently in progress or the next to be done. More...
 
uhal::exception::exceptionmAsynchronousException
 A pointer to an exception object for passing exceptions from the worker thread to the main thread. More...
 

Detailed Description

template<typename InnerProtocol>
class uhal::UDP< InnerProtocol >

Transport protocol to transfer an IPbus buffer via UDP.

Definition at line 84 of file ProtocolUDP.hpp.

Constructor & Destructor Documentation

◆ UDP() [1/2]

template<typename InnerProtocol >
uhal::UDP< InnerProtocol >::UDP ( const UDP< InnerProtocol > &  aUDP)
private

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

which connects to the same target ip/port

Parameters
aUDPa UDP-protocol object to copy

◆ UDP() [2/2]

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

Functor class to perform the actual transport, Like this to allow multithreading if desirable.

Constructor

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

Definition at line 64 of file ProtocolUDP.cpp.

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

◆ ~UDP()

template<typename InnerProtocol >
uhal::UDP< InnerProtocol >::~UDP ( )
virtual

Member Function Documentation

◆ CheckDeadline()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::CheckDeadline ( )
private

◆ connect()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::connect ( )
private

◆ dispatchExceptionHandler()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::dispatchExceptionHandler ( )
privatevirtual

◆ Flush()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::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 470 of file ProtocolUDP.cpp.

References uhal::UDP< InnerProtocol >::mAsynchronousException, uhal::UDP< InnerProtocol >::mTransportLayerMutex, and uhal::UDP< InnerProtocol >::WaitOnConditionalVariable().

◆ getMaxReplySize()

template<typename InnerProtocol >
uint32_t uhal::UDP< InnerProtocol >::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 147 of file ProtocolUDP.cpp.

◆ getMaxSendSize()

template<typename InnerProtocol >
uint32_t uhal::UDP< InnerProtocol >::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 140 of file ProtocolUDP.cpp.

◆ implementDispatch()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::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 recieve 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 110 of file ProtocolUDP.cpp.

References uhal::UDP< InnerProtocol >::connect(), uhal::UDP< InnerProtocol >::mAsynchronousException, uhal::UDP< InnerProtocol >::mDispatchBuffers, uhal::UDP< InnerProtocol >::mDispatchQueue, uhal::UDP< InnerProtocol >::mPacketsInFlight, uhal::UDP< InnerProtocol >::mSocket, uhal::UDP< InnerProtocol >::mTransportLayerMutex, ThisLocation, and uhal::UDP< InnerProtocol >::write().

◆ NotifyConditionalVariable()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::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 526 of file ProtocolUDP.cpp.

References uhal::UDP< InnerProtocol >::mConditionalVariable, uhal::UDP< InnerProtocol >::mConditionalVariableMutex, and uhal::UDP< InnerProtocol >::mFlushDone.

Referenced by uhal::UDP< InnerProtocol >::dispatchExceptionHandler(), uhal::UDP< InnerProtocol >::read(), uhal::UDP< InnerProtocol >::read_callback(), uhal::UDP< InnerProtocol >::write(), and uhal::UDP< InnerProtocol >::write_callback().

◆ operator=()

template<typename InnerProtocol >
UDP& uhal::UDP< InnerProtocol >::operator= ( const UDP< InnerProtocol > &  aUDP)
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
aUDPa UDP-protocol object to copy
Returns
reference to the current object to allow chaining of assignments

◆ read()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::read ( )
private

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

Definition at line 276 of file ProtocolUDP.cpp.

References uhal::Debug, uhal::Error, uhal::Integer(), uhal::UDP< InnerProtocol >::mDeadlineTimer, uhal::UDP< InnerProtocol >::mReplyBuffers, uhal::UDP< InnerProtocol >::mReplyMemory, uhal::UDP< InnerProtocol >::mSocket, and uhal::UDP< InnerProtocol >::NotifyConditionalVariable().

Referenced by uhal::UDP< InnerProtocol >::read_callback(), and uhal::UDP< InnerProtocol >::write_callback().

◆ read_callback()

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

◆ WaitOnConditionalVariable()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::WaitOnConditionalVariable ( )
private

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

Definition at line 537 of file ProtocolUDP.cpp.

References uhal::UDP< InnerProtocol >::mConditionalVariable, uhal::UDP< InnerProtocol >::mConditionalVariableMutex, and uhal::UDP< InnerProtocol >::mFlushDone.

Referenced by uhal::UDP< InnerProtocol >::Flush().

◆ write()

template<typename InnerProtocol >
void uhal::UDP< InnerProtocol >::write ( )
private

◆ write_callback()

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

Member Data Documentation

◆ mAsynchronousException

template<typename InnerProtocol >
uhal::exception::exception* uhal::UDP< InnerProtocol >::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 249 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::dispatchExceptionHandler(), uhal::UDP< InnerProtocol >::Flush(), uhal::UDP< InnerProtocol >::implementDispatch(), uhal::UDP< InnerProtocol >::read_callback(), and uhal::UDP< InnerProtocol >::write_callback().

◆ mConditionalVariable

template<typename InnerProtocol >
boost::condition_variable uhal::UDP< InnerProtocol >::mConditionalVariable
private

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

Definition at line 236 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::NotifyConditionalVariable(), and uhal::UDP< InnerProtocol >::WaitOnConditionalVariable().

◆ mConditionalVariableMutex

template<typename InnerProtocol >
boost::mutex uhal::UDP< InnerProtocol >::mConditionalVariableMutex
private

A mutex for use by the conditional variable.

Definition at line 234 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::NotifyConditionalVariable(), and uhal::UDP< InnerProtocol >::WaitOnConditionalVariable().

◆ mDeadlineTimer

template<typename InnerProtocol >
boost::asio::deadline_timer uhal::UDP< InnerProtocol >::mDeadlineTimer
private

◆ mDispatchBuffers

template<typename InnerProtocol >
boost::shared_ptr< Buffers > uhal::UDP< InnerProtocol >::mDispatchBuffers
private

◆ mDispatchQueue

template<typename InnerProtocol >
std::deque< boost::shared_ptr< Buffers > > uhal::UDP< InnerProtocol >::mDispatchQueue
private

◆ mDispatchThread

template<typename InnerProtocol >
boost::thread uhal::UDP< InnerProtocol >::mDispatchThread
private

The Worker thread in Multi-threaded mode.

Definition at line 220 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::~UDP().

◆ mEndpoint

template<typename InnerProtocol >
boost::asio::ip::udp::endpoint uhal::UDP< InnerProtocol >::mEndpoint
private

A shared pointer to a boost::asio udp endpoint - used in the ASIO send and receive functions (UDP has no concept of a connection)

Definition at line 204 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::write().

◆ mFlushDone

template<typename InnerProtocol >
bool uhal::UDP< InnerProtocol >::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 238 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::NotifyConditionalVariable(), and uhal::UDP< InnerProtocol >::WaitOnConditionalVariable().

◆ mIOservice

template<typename InnerProtocol >
boost::asio::io_service uhal::UDP< InnerProtocol >::mIOservice
private

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

Definition at line 198 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::~UDP().

◆ mIOserviceWork

template<typename InnerProtocol >
boost::asio::io_service::work uhal::UDP< InnerProtocol >::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 217 of file ProtocolUDP.hpp.

◆ mPacketsInFlight

template<typename InnerProtocol >
uint32_t uhal::UDP< InnerProtocol >::mPacketsInFlight
private

◆ mReplyBuffers

template<typename InnerProtocol >
boost::shared_ptr< Buffers > uhal::UDP< InnerProtocol >::mReplyBuffers
private

◆ mReplyMemory

template<typename InnerProtocol >
std::vector<uint8_t> uhal::UDP< InnerProtocol >::mReplyMemory
private

A block of memory into which we write replies, before copying them to their final destination.

Note
This should not be necessary and was, for a while, removed, with the buffer sequence created, instead, pointing to the final destinations
Tom Williams, however believes that there is a problem with scatter-gather operations of size>64 with the UDP and so has reverted it – see https://svnweb.cern.ch/trac/cactus/ticket/259#comment:17

Definition at line 214 of file ProtocolUDP.hpp.

Referenced by uhal::UDP< InnerProtocol >::read(), and uhal::UDP< InnerProtocol >::read_callback().

◆ mReplyQueue

template<typename InnerProtocol >
std::deque< boost::shared_ptr< Buffers > > uhal::UDP< InnerProtocol >::mReplyQueue
private

◆ mSocket

template<typename InnerProtocol >
boost::asio::ip::udp::socket uhal::UDP< InnerProtocol >::mSocket
private

◆ mTransportLayerMutex

template<typename InnerProtocol >
boost::mutex uhal::UDP< InnerProtocol >::mTransportLayerMutex
private

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