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.

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.

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.

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.

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.

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.

---

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

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