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

#include <uhal/ProtocolUDP.hpp>

Inheritance diagram for uhal::UDP< InnerProtocol >:

Collaboration diagram for uhal::UDP< InnerProtocol >:

Public Member Functions
	UDP (const std::string &aId, const URI &aUri)
	Constructor. 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...

UDP &	operator= (const UDP &aUDP)
	Assignment operator This reassigns the endpoint, closes the existing socket and cleans up the buffers, etc. More...

void	implementDispatch (std::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
size_t	mMaxPayloadSize
	The maximum UDP payload size (in bytes) More...

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...

std::thread	mDispatchThread
	The Worker thread in Multi-threaded mode. More...

std::mutex	mTransportLayerMutex
	A MutEx lock used to make sure the access functions are thread safe. More...

std::deque< std::shared_ptr< Buffers > >	mDispatchQueue
	The list of buffers still waiting to be sent. More...

std::deque< std::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...

std::mutex	mConditionalVariableMutex
	A mutex for use by the conditional variable. More...

std::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...

std::shared_ptr< Buffers >	mDispatchBuffers
	The send operation currently in progress. More...

std::shared_ptr< Buffers >	mReplyBuffers
	The receive operation currently in progress or the next to be done. More...

uhal::exception::exception *	mAsynchronousException
	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 82 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

aUDP	a UDP-protocol object to copy

◆ UDP() [2/2]

template<typename InnerProtocol >

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

Constructor.

Parameters

aId	the uinique identifier that the client will be given.
aUri	a struct containing the full URI of the target.

Definition at line 59 of file ProtocolUDP.cpp.

References uhal::UDP< InnerProtocol >::mIOservice.

◆ ~UDP()

template<typename InnerProtocol >

uhal::UDP< InnerProtocol >::~UDP

virtual

Destructor.

Definition at line 97 of file ProtocolUDP.cpp.

References uhal::Error, uhal::log(), uhal::Quote(), uhal::ClientInterface::returnBufferToPool(), and uhal::Type().

Member Function Documentation

◆ CheckDeadline()

template<typename InnerProtocol >

void uhal::UDP< InnerProtocol >::CheckDeadline

private

Function called by the ASIO deadline timer.

Definition at line 411 of file ProtocolUDP.cpp.

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

◆ connect()

template<typename InnerProtocol >

void uhal::UDP< InnerProtocol >::connect

private

Set up the UDP socket.

Definition at line 164 of file ProtocolUDP.cpp.

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

◆ dispatchExceptionHandler()

template<typename InnerProtocol >

void uhal::UDP< InnerProtocol >::dispatchExceptionHandler

privatevirtual

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

Definition at line 458 of file ProtocolUDP.cpp.

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

◆ 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 444 of file ProtocolUDP.cpp.

◆ 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 157 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 150 of file ProtocolUDP.cpp.

◆ implementDispatch()

template<typename InnerProtocol >

void uhal::UDP< InnerProtocol >::implementDispatch ( std::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

aBuffers the 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 121 of file ProtocolUDP.cpp.

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

◆ 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

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

Definition at line 497 of file ProtocolUDP.cpp.

◆ 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

aUDP	a 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 270 of file ProtocolUDP.cpp.

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

◆ read_callback()

template<typename InnerProtocol >

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

private

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.

Parameters

aErrorCode the error code with which the ASIO operation completed

Definition at line 295 of file ProtocolUDP.cpp.

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

◆ 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 508 of file ProtocolUDP.cpp.

◆ write()

template<typename InnerProtocol >

void uhal::UDP< InnerProtocol >::write

private

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.

Definition at line 176 of file ProtocolUDP.cpp.

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

◆ write_callback()

template<typename InnerProtocol >

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

private

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.

Parameters

aErrorCode the error code with which the ASIO operation completed

Definition at line 204 of file ProtocolUDP.cpp.

References uhal::Integer(), uhal::log(), and uhal::Quote().

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 237 of file ProtocolUDP.hpp.

◆ mConditionalVariable

template<typename InnerProtocol >

std::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 224 of file ProtocolUDP.hpp.

◆ mConditionalVariableMutex

template<typename InnerProtocol >

std::mutex uhal::UDP< InnerProtocol >::mConditionalVariableMutex

private

A mutex for use by the conditional variable.

Definition at line 222 of file ProtocolUDP.hpp.

◆ mDeadlineTimer

template<typename InnerProtocol >

boost::asio::deadline_timer uhal::UDP< InnerProtocol >::mDeadlineTimer

private

The mechanism for providing the time-out.

Definition at line 195 of file ProtocolUDP.hpp.

◆ mDispatchBuffers

template<typename InnerProtocol >

std::shared_ptr< Buffers > uhal::UDP< InnerProtocol >::mDispatchBuffers

private

The send operation currently in progress.

Definition at line 229 of file ProtocolUDP.hpp.

◆ mDispatchQueue

template<typename InnerProtocol >

std::deque< std::shared_ptr< Buffers > > uhal::UDP< InnerProtocol >::mDispatchQueue

private

The list of buffers still waiting to be sent.

Definition at line 214 of file ProtocolUDP.hpp.

◆ mDispatchThread

template<typename InnerProtocol >

std::thread uhal::UDP< InnerProtocol >::mDispatchThread

private

The Worker thread in Multi-threaded mode.

Definition at line 208 of file ProtocolUDP.hpp.

◆ 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 192 of file ProtocolUDP.hpp.

◆ 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 226 of file ProtocolUDP.hpp.

◆ 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 186 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 205 of file ProtocolUDP.hpp.

◆ mMaxPayloadSize

template<typename InnerProtocol >

size_t uhal::UDP< InnerProtocol >::mMaxPayloadSize

private

The maximum UDP payload size (in bytes)

Definition at line 183 of file ProtocolUDP.hpp.

◆ mPacketsInFlight

template<typename InnerProtocol >

uint32_t uhal::UDP< InnerProtocol >::mPacketsInFlight

private

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

Definition at line 219 of file ProtocolUDP.hpp.

◆ mReplyBuffers

template<typename InnerProtocol >

std::shared_ptr< Buffers > uhal::UDP< InnerProtocol >::mReplyBuffers

private

The receive operation currently in progress or the next to be done.

Definition at line 231 of file ProtocolUDP.hpp.

◆ 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 202 of file ProtocolUDP.hpp.

◆ mReplyQueue

template<typename InnerProtocol >

std::deque< std::shared_ptr< Buffers > > uhal::UDP< InnerProtocol >::mReplyQueue

private

The list of buffers still awaiting a reply.

Definition at line 216 of file ProtocolUDP.hpp.

◆ mSocket

template<typename InnerProtocol >

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

private

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

Definition at line 189 of file ProtocolUDP.hpp.

◆ mTransportLayerMutex

template<typename InnerProtocol >

std::mutex uhal::UDP< InnerProtocol >::mTransportLayerMutex

private

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

Definition at line 211 of file ProtocolUDP.hpp.

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

uhal/include/uhal/ProtocolUDP.hpp
uhal/src/common/ProtocolUDP.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ UDP() [1/2]

◆ UDP() [2/2]

◆ ~UDP()

Member Function Documentation

◆ CheckDeadline()

◆ connect()

◆ dispatchExceptionHandler()

◆ Flush()

◆ getMaxReplySize()

◆ getMaxSendSize()

◆ implementDispatch()

◆ NotifyConditionalVariable()

◆ operator=()

◆ read()

◆ read_callback()

◆ WaitOnConditionalVariable()

◆ write()

◆ write_callback()

Member Data Documentation

◆ mAsynchronousException

◆ mConditionalVariable

◆ mConditionalVariableMutex

◆ mDeadlineTimer

◆ mDispatchBuffers

◆ mDispatchQueue

◆ mDispatchThread

◆ mEndpoint

◆ mFlushDone

◆ mIOservice

◆ mIOserviceWork

◆ mMaxPayloadSize

◆ mPacketsInFlight

◆ mReplyBuffers

◆ mReplyMemory

◆ mReplyQueue

◆ mSocket

◆ mTransportLayerMutex