libsocket::dgram_over_stream Class Reference

Wraps a stream socket and provides a message-based API on top of it. More...

#include <dgramoverstream.hpp>

Public Member Functions
	dgram_over_stream (const dgram_over_stream &)=delete
	dgram_over_stream (stream_client_socket inner)
	dgram_over_stream (std::unique_ptr< stream_client_socket > inner)
void	enable_nagle (bool enable) const
	Set TCP_NODELAY to !enabled on the underlying socket. More...
ssize_t	sndmsg (const void *buf, size_t len)
	Send the message in buf with length len as one frame. More...
ssize_t	rcvmsg (void *dst, size_t len)
	Receive a message and store the first len bytes into buf. More...
ssize_t	sndmsg (const std::string &msg)
ssize_t	rcvmsg (std::string *dst)
	Receive a message and place it into dst. More...
ssize_t	sndmsg (const std::vector< uint8_t > &msg)
	Send the message msg as one frame. More...
ssize_t	rcvmsg (std::vector< uint8_t > *dst)
	Receive up to dst.size() bytes and store them in dst. More...

Private Member Functions
ssize_t	receive_bytes (size_t)
uint32_t	receive_header (void)
	Receive and decode length header. More...

Private Attributes
std::unique_ptr< stream_client_socket >	inner
char	prefix_buffer [FRAMING_PREFIX_LENGTH]
char	RECV_BUF [RECV_BUF_SIZE]

Static Private Attributes
static const size_t	RECV_BUF_SIZE = 256

Detailed Description

Wraps a stream socket and provides a message-based API on top of it.

Inner has to implement stream and socket methods; those are: snd(), rcv(), setsockopt(). It may not be non-blocking, as EWOULDBLOCK is not handled gracefully.

This means that if you use sndmsg() to send a frame, then the entire frame will be delivered; and the receiver will (provided it uses a dgram_over_stream socket as well) receive only the entire message (not parts of it).

The internally used format is relatively simple; it uses NBO (big-endian) fixed-size 32bit integers as prefix. The prefix encodes how many bytes are coming after it. The maximum supported frame size is 2GiB. Schema: [4* u8, *u8]

By default, Nagle's algorithm is disabled on the inner stream. This is necessary so that a message frame is sent as soon as it is written to the socket. If you send a lot of small messages and can accept smaller delays, you can enable it again using enable_nagle().

THIS CLASS IS NOT THREADSAFE.

AS THE STREAM SOCKET WILL BE CLOSED ON DESTRUCTION, IT IS NOT PERMITTED TO USE A dgram_over_stream OUTSIDE THE SCOPE OF THE ORIGINAL SOCKET.

THIS CLASS IS IN BETA STATE: IT HAS NOT BEEN TESTED EXTENSIVELY, BUT IS EXPECTED TO WORK.

Definition at line 80 of file dgramoverstream.hpp.

Member Function Documentation

enable_nagle()

void libsocket::dgram_over_stream::enable_nagle

(

bool

enabled

)

const

Set TCP_NODELAY to !enabled on the underlying socket.

TCP_NODELAY causes writes to the socket to be pushed to the network immediately. This emulates the behavior of datagram sockets, and is very useful for datagram-like use of streams, like this class implements. However, it creates slight overhead as data are not batched.

(clarification: If Nagle's algorithm is enabled, that means that TCP_NODELAY is disabled, and vice versa)

Definition at line 66 of file dgramoverstream.cpp.

sndmsg() [1/2]

ssize_t libsocket::dgram_over_stream::sndmsg	(	const void *	buf,
		size_t	len
	)

Send the message in buf with length len as one frame.

Returns

The total number of bytes sent.

Exceptions

A	socket_exception.

Definition at line 167 of file dgramoverstream.cpp.

Here is the caller graph for this function:

rcvmsg() [1/3]

ssize_t libsocket::dgram_over_stream::rcvmsg	(	void *	dst,
		size_t	len
	)

Receive a message and store the first len bytes into buf.

Returns

The number of bytes received.

Exceptions

A	socket_exception.

Bytes in the message beyond len are discarded.

Definition at line 187 of file dgramoverstream.cpp.

Here is the call graph for this function:

rcvmsg() [2/3]

ssize_t libsocket::dgram_over_stream::rcvmsg

(

std::string *

dst

)

Receive a message and place it into dst.

No more than dst.size() bytes will be received and placed into dst.

Definition at line 81 of file dgramoverstream.cpp.

Here is the call graph for this function:

sndmsg() [2/2]

ssize_t libsocket::dgram_over_stream::sndmsg

(

const std::vector< uint8_t > &

msg

)

Send the message msg as one frame.

Returns

How many bytes were sent; should be msg.size().

Exceptions

socket_exception

Definition at line 117 of file dgramoverstream.cpp.

Here is the call graph for this function:

rcvmsg() [3/3]

ssize_t libsocket::dgram_over_stream::rcvmsg

(

std::vector< uint8_t > *

dst

)

Receive up to dst.size() bytes and store them in dst.

Returns

Number of bytes actually received.

Exceptions

socket_exception

Resize dst before calling in order to adjust the number of bytes you will receive.

Definition at line 129 of file dgramoverstream.cpp.

Here is the call graph for this function:

receive_header()

uint32_t libsocket::dgram_over_stream::receive_header ( void  )

private

Receive and decode length header.

Returns

The expected length received.

Exceptions

socket_exception

Definition at line 240 of file dgramoverstream.cpp.

Here is the caller graph for this function:

---

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

• headers/dgramoverstream.hpp
• C++/dgramoverstream.cpp