dfx::Server::TcpSession Class Reference

One asynchronous TCP connection managed by TcpServer. More...

#include <dfx-server/TcpSession.hpp>

Inheritance diagram for dfx::Server::TcpSession:

Collaboration diagram for dfx::Server::TcpSession:

Public Types
enum class	TimeoutPolicy {   Disabled , Manual , ResetOnRead , ResetOnWrite ,   ResetOnAny }
	Policy describing when I/O activity resets the inactivity timeout. More...

Public Member Functions
	TcpSession (std::string host, std::string serv, TcpServer &server, std::chrono::milliseconds initialTimeout)
	Construct a session descriptor (not yet bound to a socket).
	DISABLE_COPY_AND_MOVE (TcpSession)
	TcpSession are not copyable and not movable.
virtual	~TcpSession ()=default
	Virtual destructor for polymorphic session types.
FdWatch::BorrowedFd	socket () const noexcept
	Borrowed socket FD (valid after init()).
std::string const &	host () const noexcept
	Remote host string.
std::string const &	serv () const noexcept
	Remote service/port string.
void	init (FdWatch::OwnedFd socket, FdWatch::Poller &poller)
	Bind the accepted socket to this session and register it to the poller.
bool	subtractTimeAndCheckTimeout (std::chrono::milliseconds time)
	Decrease the remaining time before timeout and report expiration.
std::chrono::milliseconds	initialTimeout () const noexcept
	Current configured initial timeout value.
void	setInitialTimeout (std::chrono::milliseconds timeout)
	Update the initial timeout value.
void	sendMessage (std::vector< uint8_t > const &message)
	Queue an outgoing message to be sent asynchronously.

Protected Member Functions
void	resetTimeout ()
	Reset the remaining timeout countdown to the configured initial value.
void	terminate ()
	Ask the owning server to terminate this session.
void	setMaxDataQueueSize (std::size_t size)
	Set the maximum number of queued outgoing messages.
std::size_t	maxDataQueueSize () const noexcept
	Maximum number of queued outgoing messages.
virtual void	handleMessage (std::vector< uint8_t > message)=0
	Handle one received message payload.

Protected Attributes
std::string	_host
	Remote host string.
std::string	_serv
	Remote service/port string.
TimeoutPolicy	_timeoutPolicy = TimeoutPolicy::ResetOnAny
	Timeout reset policy.

Detailed Description

One asynchronous TCP connection managed by TcpServer.

TcpSession represents a single client connection accepted by a TcpServer. It is designed to be driven by a FdWatch::Poller (typically epoll-based): the session registers its socket in the poller and reacts to readiness events.

This class provides:

• basic connection identity (remote host/service strings),
• asynchronous send queueing with backpressure handling,
• timeout tracking with configurable reset policies,
• a single virtual message handler entry point for derived session types.

Session lifecycle

The typical flow is:

1. A server accepts a socket and creates a concrete session (derived class).
2. The server calls init() to give ownership of the accepted socket and register it into the poller.
3. The poller triggers callbacks which perform reads/writes and invoke handleMessage() for received payloads.
4. The server may periodically call subtractTimeAndCheckTimeout() (usually from a timer) to enforce inactivity timeouts.

Timeout model

The session tracks "time before timeout" as a countdown. Each time slice, the server calls subtractTimeAndCheckTimeout(). Whether activity resets the timeout depends on TimeoutPolicy :

• Disabled: timeout never triggers.
• Manual: timeout only changes when the session explicitly calls resetTimeout().
• ResetOnRead: reading data resets the timeout.
• ResetOnWrite: writing data resets the timeout.
• ResetOnAny: either reading or writing resets the timeout (default).

Sending data

sendMessage() enqueues outgoing bytes. Actual transmission occurs when the socket becomes writable.

The queue is bounded by maxDataQueueSize(). If the limit is exceeded, data is dropped and a warning is logged.

Note

TcpSession exposes received payloads to handleMessage() as a raw byte vector. The framing / protocol is defined by derived session implementations.

TcpSession derives from std::enable_shared_from_this because it is typically held by the server and used from poller callbacks that may outlive the initiating call stack.

Member Enumeration Documentation

TimeoutPolicy

enum class dfx::Server::TcpSession::TimeoutPolicy

strong

Policy describing when I/O activity resets the inactivity timeout.

Enumerator
Disabled	Timeouts are disabled.
Manual	Timeout is only reset explicitly (via resetTimeout()).
ResetOnRead	Reading data resets the timeout.
ResetOnWrite	Writing data resets the timeout.
ResetOnAny	Any I/O activity resets the timeout (default).

Constructor & Destructor Documentation

TcpSession()

dfx::Server::TcpSession::TcpSession	(	std::string	host,
		std::string	serv,
		TcpServer &	server,
		std::chrono::milliseconds	initialTimeout )

Construct a session descriptor (not yet bound to a socket).

The accepted socket is provided later through init().

Parameters

host	Remote host string (typically from getnameinfo / accept).
serv	Remote service/port string.
server	Reference to the owning server.
initialTimeout	Initial inactivity timeout for the new session.

~TcpSession()

virtual dfx::Server::TcpSession::~TcpSession ( )

virtualdefault

Virtual destructor for polymorphic session types.

Member Function Documentation

DISABLE_COPY_AND_MOVE()

dfx::Server::TcpSession::DISABLE_COPY_AND_MOVE

(

TcpSession

)

TcpSession are not copyable and not movable.

handleMessage()

virtual void dfx::Server::TcpSession::handleMessage ( std::vector< uint8_t > message )

protectedpure virtual

Handle one received message payload.

Derived session types implement the protocol/framing logic and decide how to interpret the received bytes.

Parameters

message

Raw payload bytes received from the socket.

Implemented in dfx::Pcapng::WriteOnlySession.

host()

std::string const & dfx::Server::TcpSession::host ( ) const

inlinenoexcept

Remote host string.

init()

void dfx::Server::TcpSession::init	(	FdWatch::OwnedFd	socket,
		FdWatch::Poller &	poller )

Bind the accepted socket to this session and register it to the poller.

Stores the socket in a FdWatch::PollerFd and registers read/write interests as required by the internal send/receive state.

This must be called once before any I/O can occur.

Parameters

socket	Accepted socket FD (ownership is transferred to the session).
poller	Poller used for asynchronous readiness notifications.

initialTimeout()

std::chrono::milliseconds dfx::Server::TcpSession::initialTimeout ( ) const

inlinenoexcept

Current configured initial timeout value.

maxDataQueueSize()

std::size_t dfx::Server::TcpSession::maxDataQueueSize ( ) const

inlineprotectednoexcept

Maximum number of queued outgoing messages.

resetTimeout()

void dfx::Server::TcpSession::resetTimeout ( )

protected

Reset the remaining timeout countdown to the configured initial value.

Called internally based on TimeoutPolicy, and may be called by derived classes when using TimeoutPolicy::Manual.

sendMessage()

void dfx::Server::TcpSession::sendMessage

(

std::vector< uint8_t > const &

message

)

Queue an outgoing message to be sent asynchronously.

This method does not block. Data is sent immediately if possible otherwise it is queued and transmitted when the socket is writable. The queue is bounded by maxDataQueueSize().

Parameters

message

Payload bytes to send.

serv()

std::string const & dfx::Server::TcpSession::serv ( ) const

inlinenoexcept

Remote service/port string.

setInitialTimeout()

void dfx::Server::TcpSession::setInitialTimeout

(

std::chrono::milliseconds

timeout

)

Update the initial timeout value.

This updates the configured initial timeout. Time already spent before this call is kept. If the timeout was set to 1000 ms and 400 ms passed (meaning 600 ms remaining before te timeout) at the time you call this function with a new timeout of 2000 ms, then the socket will expire in 1600 ms.

Parameters

timeout

New timeout value.

setMaxDataQueueSize()

void dfx::Server::TcpSession::setMaxDataQueueSize ( std::size_t size )

protected

Set the maximum number of queued outgoing messages.

If the queue grows beyond this limit, the session will apply backpressure behavior and drop messages.

Parameters

size	New maximum queue size in message count.

socket()

FdWatch::BorrowedFd dfx::Server::TcpSession::socket ( ) const

inlinenoexcept

Borrowed socket FD (valid after init()).

subtractTimeAndCheckTimeout()

bool dfx::Server::TcpSession::subtractTimeAndCheckTimeout

(

std::chrono::milliseconds

time

)

Decrease the remaining time before timeout and report expiration.

This is typically invoked periodically by the server timer. Whether activity resets the countdown depends on TimeoutPolicy.

Parameters

time	Amount of time to subtract from the remaining timeout.

Returns

True if the timeout has expired, false otherwise.

terminate()

void dfx::Server::TcpSession::terminate ( )

protected

Ask the owning server to terminate this session.

This is the session-side hook for closing and removing the session from the server’s registry. The actual removal is performed by TcpServer.

See also

TcpServer::terminateSession()

Member Data Documentation

_host

std::string dfx::Server::TcpSession::_host

protected

Remote host string.

_serv

std::string dfx::Server::TcpSession::_serv

protected

Remote service/port string.

_timeoutPolicy

TimeoutPolicy dfx::Server::TcpSession::_timeoutPolicy = TimeoutPolicy::ResetOnAny

protected

Timeout reset policy.

---

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

• lib/dfx-server/TcpSession.hpp