basic asynchronous socket class. More...

#include <async_socket.hpp>

Inheritance diagram for join::BasicAsyncSocket< Protocol, Proactor, OpCount >:

Collaboration diagram for join::BasicAsyncSocket< Protocol, Proactor, OpCount >:

[legend]

Public Types
using	Socket = typename Protocol::Socket

using	Endpoint = typename Protocol::Endpoint

using	AsyncWait = BasicAsyncWait<Protocol, Proactor>

using	WaitHandler = typename AsyncWait::Wait

using	OpArena = LocalMem::Allocator<_opCount, _opSize>

Public Member Functions
BasicAsyncSocket &	operator= (const BasicAsyncSocket &other)=delete
	copy assignment operator.

BasicAsyncSocket &	operator= (BasicAsyncSocket &&other) noexcept
	move assignment operator.

	~BasicAsyncSocket ()
	destroy the socket instance.

int	open (const Protocol &protocol=Protocol()) noexcept
	open socket using the given protocol.

void	close () noexcept
	close the socket, cancelling the operations in flight.

template<size_t Count, size_t Size>
int	registerBufferRing (uint16_t group, LocalMem::Allocator< Count, Size > &arena)
	register a provided buffer ring on the proactor driving this socket.

int	unregisterBufferRing (uint16_t group)
	unregister a provided buffer ring from the proactor driving this socket.

ssize_t	asyncWait (bool wantRead, bool wantWrite, WaitHandler handler, bool flush=true) noexcept
	start an asynchronous wait for the socket to become ready in one direction.

ssize_t	asyncWaitMulti (bool wantRead, bool wantWrite, WaitHandler handler, bool flush=true) noexcept
	start an asynchronous multishot wait, staying armed until cancelled or failed.

int	cancel (size_t index) noexcept
	cancel the operation stored at the given index, if in flight.

Endpoint	localEndpoint () const noexcept
	determine the local endpoint associated with this socket.

bool	opened () const noexcept
	check if the socket is opened.

int	family () const noexcept
	get address family.

int	type () const noexcept
	get the protocol communication semantic.

int	protocol () const noexcept
	get socket protocol.

int	handle () const noexcept
	get socket native handle.

Public Member Functions inherited from join::CompletionHandler
	CompletionHandler ()=default
	create instance.

	CompletionHandler (const CompletionHandler &other)=default
	copy constructor.

CompletionHandler &	operator= (const CompletionHandler &other)=default
	copy assignment operator.

	CompletionHandler (CompletionHandler &&other)=default
	move constructor.

CompletionHandler &	operator= (CompletionHandler &&other)=default
	move assignment operator.

virtual	~CompletionHandler ()=default
	destroy instance.

Static Public Attributes
static constexpr size_t	_opCount = OpCount
	number of operations in flight.

static constexpr size_t	_opSize = nextPow2 (AsyncOp<Protocol, Proactor>::maxSize)
	size of an operation slot.

Protected Member Functions
	BasicAsyncSocket (Proactor &proactor=ProactorThread::proactor())
	create the socket instance.

	BasicAsyncSocket (Socket &&sock, Proactor &proactor=ProactorThread::proactor())
	create the socket instance adopting an already opened socket.

	BasicAsyncSocket (const BasicAsyncSocket &other)=delete
	copy constructor.

	BasicAsyncSocket (BasicAsyncSocket &&other) noexcept
	move constructor.

void	onComplete (IoOperation &op, int result) override
	method called when an operation completes.

void	onCancel (IoOperation &op, int result) override
	method called when an operation is cancelled.

virtual void	dispatch (IoOperation &op, const std::error_code &code, size_t size) noexcept
	invoke the completion handler of the given operation, then release it.

void	completeWait (AsyncWait *wait, const std::error_code &code, size_t revents) noexcept
	invoke the wait completion handler.

template<class Op >
Op *	allocateOp () noexcept
	allocate an operation in the arena.

template<class Op >
void	releaseOp (Op *operation) noexcept
	return an operation to the arena.

void	suspendAll () noexcept
	suspend every operation in flight.

void	resumeAll () noexcept
	resume every suspended operation, redirecting it to this handler.

void	cancelAll () noexcept
	cancel every operation in flight.

bool	pendingAny () const noexcept
	check if at least one operation is in flight or completing.

int	cancelOp (IoOperation *op) noexcept
	cancel the given operation, if in flight.

bool	inFlight (const IoOperation &op) const noexcept
	check if an operation is in flight.

bool	pending (const IoOperation &op) const noexcept
	check if an operation is in flight or completing.

Protected Member Functions inherited from join::CompletionHandler

Protected Attributes
Proactor *	_proactor
	proactor driving the operations.

Socket	_socket
	underlying synchronous socket.

OpArena	_arena
	operations arena.

std::array< std::atomic< IoOperation * >, _opCount >	_ops {}
	operations in flight.

Detailed Description

template<class Protocol, class Proactor = BasicProactor, size_t OpCount = 16>
class join::BasicAsyncSocket< Protocol, Proactor, OpCount >

basic asynchronous socket class.

Member Typedef Documentation

◆ AsyncWait

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

using join::BasicAsyncSocket< Protocol, Proactor, OpCount >::AsyncWait = BasicAsyncWait<Protocol, Proactor>

◆ Endpoint

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

using join::BasicAsyncSocket< Protocol, Proactor, OpCount >::Endpoint = typename Protocol::Endpoint

◆ OpArena

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

using join::BasicAsyncSocket< Protocol, Proactor, OpCount >::OpArena = LocalMem::Allocator<_opCount, _opSize>

◆ Socket

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

using join::BasicAsyncSocket< Protocol, Proactor, OpCount >::Socket = typename Protocol::Socket

◆ WaitHandler

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

using join::BasicAsyncSocket< Protocol, Proactor, OpCount >::WaitHandler = typename AsyncWait::Wait

Constructor & Destructor Documentation

◆ BasicAsyncSocket() [1/4]

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

join::BasicAsyncSocket< Protocol, Proactor, OpCount >::BasicAsyncSocket ( Proactor & proactor = ProactorThread::proactor () )

inlineexplicitprotected

create the socket instance.

Parameters

proactor proactor driving the operations.

◆ BasicAsyncSocket() [2/4]

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

join::BasicAsyncSocket< Protocol, Proactor, OpCount >::BasicAsyncSocket	(	Socket &&	sock,
		Proactor &	proactor = ProactorThread::proactor () )

inlineexplicitprotected

create the socket instance adopting an already opened socket.

Parameters

sock	socket to adopt.
proactor	proactor driving the operations.

◆ BasicAsyncSocket() [3/4]

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

join::BasicAsyncSocket< Protocol, Proactor, OpCount >::BasicAsyncSocket ( const BasicAsyncSocket< Protocol, Proactor, OpCount > & other )

protecteddelete

copy constructor.

Parameters

other other object to copy.

◆ BasicAsyncSocket() [4/4]

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

join::BasicAsyncSocket< Protocol, Proactor, OpCount >::BasicAsyncSocket ( BasicAsyncSocket< Protocol, Proactor, OpCount > && other )

inlineprotectednoexcept

move constructor.

Parameters

other other object to move.

◆ ~BasicAsyncSocket()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

join::BasicAsyncSocket< Protocol, Proactor, OpCount >::~BasicAsyncSocket ( )

inline

destroy the socket instance.

Member Function Documentation

◆ allocateOp()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

template<class Op >

Op * join::BasicAsyncSocket< Protocol, Proactor, OpCount >::allocateOp ( )

inlineprotectednoexcept

allocate an operation in the arena.

Returns: allocated operation, or nullptr if the arena is exhausted.

◆ asyncWait()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

ssize_t join::BasicAsyncSocket< Protocol, Proactor, OpCount >::asyncWait	(	bool	wantRead,
		bool	wantWrite,
		WaitHandler	handler,
		bool	flush = true )

inlinenoexcept

start an asynchronous wait for the socket to become ready in one direction.

Parameters

wantRead	wait until the socket is readable.
wantWrite	wait until the socket is writable.
handler	handler invoked on completion.
flush	flush the submission queue.

Returns: index of the operation on success, -1 on failure.

◆ asyncWaitMulti()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

ssize_t join::BasicAsyncSocket< Protocol, Proactor, OpCount >::asyncWaitMulti	(	bool	wantRead,
		bool	wantWrite,
		WaitHandler	handler,
		bool	flush = true )

inlinenoexcept

start an asynchronous multishot wait, staying armed until cancelled or failed.

Parameters

wantRead	wait until the socket is readable.
wantWrite	wait until the socket is writable.
handler	handler invoked on each completion, it must drain the socket or be invoked again at once.
flush	flush the submission queue.

Returns: index of the operation on success, -1 on failure.

◆ cancel()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::cancel ( size_t index )

inlinenoexcept

cancel the operation stored at the given index, if in flight.

Parameters

index index of the operation to cancel.

Returns: 0 on success, -1 on failure.

◆ cancelAll()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::cancelAll ( )

inlineprotectednoexcept

cancel every operation in flight.

◆ cancelOp()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::cancelOp ( IoOperation * op )

inlineprotectednoexcept

cancel the given operation, if in flight.

Parameters

op	operation to cancel.

Returns: 0 on success, -1 on failure.

◆ close()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::close ( )

inlinenoexcept

close the socket, cancelling the operations in flight.

◆ completeWait()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::completeWait	(	AsyncWait *	wait,
		const std::error_code &	code,
		size_t	revents )

inlineprotectednoexcept

invoke the wait completion handler.

Parameters

wait	completed wait operation.
code	error code reported by the kernel.
revents	ready events.

◆ dispatch()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

virtual void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::dispatch	(	IoOperation &	op,
		const std::error_code &	code,
		size_t	size )

inlineprotectedvirtualnoexcept

invoke the completion handler of the given operation, then release it.

Parameters

op	completed operation.
code	error code reported by the kernel.
size	number of bytes transferred, or ready events.

Reimplemented in join::BasicAsyncRawSocket< Protocol, Proactor, OpCount >, and join::BasicAsyncRawSocket< Protocol, BasicProactor, 16 >.

◆ family()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::family ( ) const

inlinenoexcept

get address family.

Returns: address family.

◆ handle()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::handle ( ) const

inlinenoexcept

get socket native handle.

Returns: socket native handle.

◆ inFlight()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

bool join::BasicAsyncSocket< Protocol, Proactor, OpCount >::inFlight ( const IoOperation & op ) const

inlineprotectednoexcept

check if an operation is in flight.

Parameters

op	operation to check.

Returns: true if the operation is in flight, false otherwise.

◆ localEndpoint()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

Endpoint join::BasicAsyncSocket< Protocol, Proactor, OpCount >::localEndpoint ( ) const

inlinenoexcept

determine the local endpoint associated with this socket.

Returns: local endpoint.

◆ onCancel()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::onCancel	(	IoOperation &	op,
		int	result )

inlineoverrideprotectedvirtual

method called when an operation is cancelled.

Parameters

op	cancelled operation.
result	negative errno.

Reimplemented from join::CompletionHandler.

◆ onComplete()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::onComplete	(	IoOperation &	op,
		int	result )

inlineoverrideprotectedvirtual

method called when an operation completes.

Parameters

op	completed operation.
result	number of bytes transferred, or negative errno.

Reimplemented from join::CompletionHandler.

◆ open()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::open ( const Protocol & protocol = Protocol () )

inlinenoexcept

open socket using the given protocol.

Parameters

protocol protocol to use.

Returns: 0 on success, -1 on failure.

◆ opened()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

bool join::BasicAsyncSocket< Protocol, Proactor, OpCount >::opened ( ) const

inlinenoexcept

check if the socket is opened.

Returns: true if opened, false otherwise.

◆ operator=() [1/2]

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

BasicAsyncSocket & join::BasicAsyncSocket< Protocol, Proactor, OpCount >::operator= ( BasicAsyncSocket< Protocol, Proactor, OpCount > && other )

inlinenoexcept

move assignment operator.

Parameters

other other object to assign.

Returns: assigned object.

◆ operator=() [2/2]

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

BasicAsyncSocket & join::BasicAsyncSocket< Protocol, Proactor, OpCount >::operator= ( const BasicAsyncSocket< Protocol, Proactor, OpCount > & other )

delete

copy assignment operator.

Parameters

other other object to assign.

Returns: assigned object.

◆ pending()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

bool join::BasicAsyncSocket< Protocol, Proactor, OpCount >::pending ( const IoOperation & op ) const

inlineprotectednoexcept

check if an operation is in flight or completing.

Parameters

op	operation to check.

Returns: true if the operation is in flight or completing, false otherwise.

◆ pendingAny()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

bool join::BasicAsyncSocket< Protocol, Proactor, OpCount >::pendingAny ( ) const

inlineprotectednoexcept

check if at least one operation is in flight or completing.

Returns: true if at least one operation is in flight or completing, false otherwise.

◆ protocol()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::protocol ( ) const

inlinenoexcept

get socket protocol.

Returns: socket protocol.

◆ registerBufferRing()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

template<size_t Count, size_t Size>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::registerBufferRing	(	uint16_t	group,
		LocalMem::Allocator< Count, Size > &	arena )

inline

register a provided buffer ring on the proactor driving this socket.

Parameters

group	buffer group id.
arena	arena owning the buffers, reserved until the ring is unregistered, must outlive the proactor.

Returns: 0 on success, -1 on failure.

Exceptions

std::system_error if the descriptor ring cannot be mapped.

◆ releaseOp()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

template<class Op >

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::releaseOp ( Op * operation )

inlineprotectednoexcept

return an operation to the arena.

Parameters

operation operation to release.

◆ resumeAll()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::resumeAll ( )

inlineprotectednoexcept

resume every suspended operation, redirecting it to this handler.

◆ suspendAll()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

void join::BasicAsyncSocket< Protocol, Proactor, OpCount >::suspendAll ( )

inlineprotectednoexcept

suspend every operation in flight.

◆ type()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::type ( ) const

inlinenoexcept

get the protocol communication semantic.

Returns: the protocol communication semantic.

◆ unregisterBufferRing()

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

int join::BasicAsyncSocket< Protocol, Proactor, OpCount >::unregisterBufferRing ( uint16_t group )

inline

unregister a provided buffer ring from the proactor driving this socket.

Parameters

group buffer group id.

Returns: 0 on success, -1 on failure.

Member Data Documentation

◆ _arena

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

OpArena join::BasicAsyncSocket< Protocol, Proactor, OpCount >::_arena

protected

operations arena.

◆ _opCount

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

size_t join::BasicAsyncSocket< Protocol, Proactor, OpCount >::_opCount = OpCount

staticconstexpr

number of operations in flight.

◆ _ops

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

std::array<std::atomic<IoOperation*>, _opCount> join::BasicAsyncSocket< Protocol, Proactor, OpCount >::_ops {}

protected

operations in flight.

◆ _opSize

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

size_t join::BasicAsyncSocket< Protocol, Proactor, OpCount >::_opSize = nextPow2 (AsyncOp<Protocol, Proactor>::maxSize)

staticconstexpr

size of an operation slot.

◆ _proactor

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

Proactor* join::BasicAsyncSocket< Protocol, Proactor, OpCount >::_proactor

protected

proactor driving the operations.

◆ _socket

template<class Protocol , class Proactor = BasicProactor, size_t OpCount = 16>

Socket join::BasicAsyncSocket< Protocol, Proactor, OpCount >::_socket

protected

underlying synchronous socket.

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

core/include/join/async_socket.hpp
core/include/join/protocol.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ AsyncWait

◆ Endpoint

◆ OpArena

◆ Socket

◆ WaitHandler

Constructor & Destructor Documentation

◆ BasicAsyncSocket() [1/4]

◆ BasicAsyncSocket() [2/4]

◆ BasicAsyncSocket() [3/4]

◆ BasicAsyncSocket() [4/4]

◆ ~BasicAsyncSocket()

Member Function Documentation

◆ allocateOp()

◆ asyncWait()

◆ asyncWaitMulti()

◆ cancel()

◆ cancelAll()

◆ cancelOp()

◆ close()

◆ completeWait()

◆ dispatch()

◆ family()

◆ handle()

◆ inFlight()

◆ localEndpoint()

◆ onCancel()

◆ onComplete()

◆ open()

◆ opened()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pending()

◆ pendingAny()

◆ protocol()

◆ registerBufferRing()

◆ releaseOp()

◆ resumeAll()

◆ suspendAll()

◆ type()

◆ unregisterBufferRing()

Member Data Documentation

◆ _arena

◆ _opCount

◆ _ops

◆ _opSize

◆ _proactor

◆ _socket