caf::net::lp::framing Class Reference

Implements length-prefix framing for discretizing a Byte stream into messages of varying size. More...

#include <framing.hpp>

Inheritance diagram for caf::net::lp::framing:

Public Types
using	upper_layer_ptr = std::unique_ptr< lp::upper_layer >

Public Member Functions
	framing (upper_layer_ptr up)
error	start (octet_stream::lower_layer *down) override
	Initializes the upper layer.
void	abort (const error &reason) override
	Called by the lower layer for cleaning up any state in case of an error or when disposed.
ptrdiff_t	consume (byte_span buffer, byte_span delta) override
	Consumes bytes from the lower layer.
void	prepare_send () override
	Gives the upper layer an opportunity to add additional data to the output buffer.
bool	done_sending () override
	Queries whether all pending data has been sent.
multiplexer &	mpx () noexcept override
	Returns the multiplexer instance that executes this protocol stack.
bool	can_send_more () const noexcept override
	Queries whether the output device can accept more data straight away.
void	request_messages () override
	Pulls messages from the transport until calling suspend_reading.
void	suspend_reading () override
	Stops reading messages until calling request_messages.
bool	is_reading () const noexcept override
	Queries whether the lower layer is currently reading from its input device.
void	write_later () override
	Triggers a write callback after the write device signals downstream capacity.
void	begin_message () override
	Prepares the layer for an outgoing message, e.g., by allocating an output buffer as necessary.
byte_buffer &	message_buffer () override
	Returns a reference to the buffer for assembling the current message.
bool	end_message () override
	Seals and prepares a message for transfer.
void	shutdown () override
	Shuts down any connection or session gracefully.
virtual error	start (lower_layer *down)=0
	Initializes the upper layer.
virtual ptrdiff_t	consume (byte_span buffer, byte_span delta)=0
	Consumes bytes from the lower layer.
virtual void	prepare_send ()=0
	Gives the upper layer an opportunity to add additional data to the output buffer.
virtual bool	done_sending ()=0
	Queries whether all pending data has been sent.
virtual void	abort (const error &reason)=0
	Called by the lower layer for cleaning up any state in case of an error or when disposed.
virtual void	request_messages ()=0
	Pulls messages from the transport until calling suspend_reading.
virtual void	suspend_reading ()=0
	Stops reading messages until calling request_messages.
virtual void	begin_message ()=0
	Prepares the layer for an outgoing message, e.g., by allocating an output buffer as necessary.
virtual byte_buffer &	message_buffer ()=0
	Returns a reference to the buffer for assembling the current message.
virtual bool	end_message ()=0
	Seals and prepares a message for transfer.
Public Member Functions inherited from caf::net::generic_lower_layer
virtual multiplexer &	mpx () noexcept=0
	Returns the multiplexer instance that executes this protocol stack.
virtual bool	can_send_more () const noexcept=0
	Queries whether the output device can accept more data straight away.
virtual bool	is_reading () const noexcept=0
	Queries whether the lower layer is currently reading from its input device.
virtual void	write_later ()=0
	Triggers a write callback after the write device signals downstream capacity.
virtual void	shutdown ()=0
	Shuts down any connection or session gracefully.
virtual void	shutdown (const error &reason)
	Shuts down any connection or session due to an error.

Static Public Member Functions
static std::unique_ptr< framing >	make (upper_layer_ptr up)
static std::pair< size_t, byte_span >	split (byte_span buffer) noexcept

Static Public Attributes
static constexpr size_t	hdr_size = sizeof(uint32_t)
static constexpr size_t	max_message_length = INT32_MAX - sizeof(uint32_t)

Detailed Description

Implements length-prefix framing for discretizing a Byte stream into messages of varying size.

The framing uses 4 Bytes for the length prefix, but messages (including the 4 Bytes for the length prefix) are limited to a maximum size of INT32_MAX. This limitation comes from the POSIX API (recv) on 32-bit platforms.

Member Function Documentation

abort()

void caf::net::lp::framing::abort ( const error &  reason )

overridevirtual

Called by the lower layer for cleaning up any state in case of an error or when disposed.

Implements caf::net::generic_upper_layer.

begin_message()

void caf::net::lp::framing::begin_message ( )

overridevirtual

Prepares the layer for an outgoing message, e.g., by allocating an output buffer as necessary.

Implements caf::net::lp::lower_layer.

can_send_more()

bool caf::net::lp::framing::can_send_more ( ) const

overridevirtualnoexcept

Queries whether the output device can accept more data straight away.

Implements caf::net::generic_lower_layer.

consume()

ptrdiff_t caf::net::lp::framing::consume ( byte_span  buffer, byte_span  delta  )

overridevirtual

Consumes bytes from the lower layer.

Parameters

buffer	Available bytes to read.
delta	Bytes that arrived since last calling this function.

Returns

The number of consumed bytes. May be zero if waiting for more input or negative to signal an error.

Implements caf::net::octet_stream::upper_layer.

done_sending()

bool caf::net::lp::framing::done_sending ( )

overridevirtual

Queries whether all pending data has been sent.

The lower calls this function to decide whether it has to wait for write events on the socket.

Implements caf::net::generic_upper_layer.

end_message()

bool caf::net::lp::framing::end_message ( )

overridevirtual

Seals and prepares a message for transfer.

Note

When returning false, clients must also call down.set_read_error(...) with an appropriate error code.

Implements caf::net::lp::lower_layer.

is_reading()

bool caf::net::lp::framing::is_reading ( ) const

overridevirtualnoexcept

Queries whether the lower layer is currently reading from its input device.

Implements caf::net::generic_lower_layer.

message_buffer()

byte_buffer & caf::net::lp::framing::message_buffer ( )

overridevirtual

Returns a reference to the buffer for assembling the current message.

Users may only call this function and write to the buffer between calling begin_message() and end_message().

Note

The lower layers may pre-fill the buffer, e.g., to prefix custom headers.

Implements caf::net::lp::lower_layer.

mpx()

multiplexer & caf::net::lp::framing::mpx ( )

overridevirtualnoexcept

Returns the multiplexer instance that executes this protocol stack.

Implements caf::net::generic_lower_layer.

prepare_send()

void caf::net::lp::framing::prepare_send ( )

overridevirtual

Gives the upper layer an opportunity to add additional data to the output buffer.

Implements caf::net::generic_upper_layer.

request_messages()

void caf::net::lp::framing::request_messages ( )

overridevirtual

Pulls messages from the transport until calling suspend_reading.

Implements caf::net::lp::lower_layer.

shutdown()

void caf::net::lp::framing::shutdown ( )

overridevirtual

Shuts down any connection or session gracefully.

Any pending data gets flushed before closing the socket.

Implements caf::net::generic_lower_layer.

start()

error caf::net::lp::framing::start ( octet_stream::lower_layer *  down )

overridevirtual

Initializes the upper layer.

Parameters

down	A pointer to the lower layer that remains valid for the lifetime of the upper layer.

Implements caf::net::octet_stream::upper_layer.

suspend_reading()

void caf::net::lp::framing::suspend_reading ( )

overridevirtual

Stops reading messages until calling request_messages.

Implements caf::net::lp::lower_layer.

write_later()

void caf::net::lp::framing::write_later ( )

overridevirtual

Triggers a write callback after the write device signals downstream capacity.

Does nothing if this layer is already writing.

Implements caf::net::generic_lower_layer.

---

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

• libcaf_net/caf/net/lp/framing.hpp
• libcaf_net/caf/net/lp/framing.cpp