Sponge
CS144's user-space TCP library
Public Member Functions | Private Member Functions | Private Attributes | List of all members
TCPSpongeSocket< AdaptT > Class Template Reference

Multithreaded wrapper around TCPConnection that approximates the Unix sockets API. More...

#include <tcp_sponge_socket.hh>

Inheritance diagram for TCPSpongeSocket< AdaptT >:
Inheritance graph
[legend]

Public Member Functions

 TCPSpongeSocket (AdaptT &&datagram_interface)
 Construct from the interface that the TCPConnection thread will use to read and write datagrams. More...
 
 ~TCPSpongeSocket ()
 When a connected socket is destructed, it will send a RST. More...
 
void connect (const TCPConfig &c_tcp, const FdAdapterConfig &c_ad)
 Connect using the specified configurations; blocks until connect succeeds or fails. More...
 
void listen_and_accept (const TCPConfig &c_tcp, const FdAdapterConfig &c_ad)
 Listen and accept using the specified configurations; blocks until accept succeeds or fails. More...
 
void wait_until_closed ()
 

This object cannot be safely moved or copied, since it is in use by two threads simultaneously

 TCPSpongeSocket (const TCPSpongeSocket &)=delete
 
 TCPSpongeSocket (TCPSpongeSocket &&)=delete
 
TCPSpongeSocketoperator= (const TCPSpongeSocket &)=delete
 
TCPSpongeSocketoperator= (TCPSpongeSocket &&)=delete
 

Some methods of the parent Socket wouldn't work as expected on the TCP socket, so delete them

void bind (const Address &address)=delete
 
Address local_address () const =delete
 
Address peer_address () const =delete
 
void set_reuseaddr ()=delete
 
- Public Member Functions inherited from LocalStreamSocket
 LocalStreamSocket (FileDescriptor &&fd)
 Construct from a file descriptor. More...
 
- Public Member Functions inherited from Socket
void bind (const Address &address)
 Bind a socket to a specified address with bind(2), usually for listen/accept. More...
 
void connect (const Address &address)
 Connect a socket to a specified peer address with connect(2). More...
 
Address local_address () const
 Get local address of socket with getsockname(2). More...
 
Address peer_address () const
 Get peer address of socket with getpeername(2). More...
 
void set_reuseaddr ()
 Allow local address to be reused sooner via SO_REUSEADDR. More...
 
void shutdown (const int how)
 Shut down a socket via shutdown(2). More...
 
- Public Member Functions inherited from FileDescriptor
 FileDescriptor (const int fd)
 Construct from a file descriptor number returned by the kernel. More...
 
 ~FileDescriptor ()=default
 Free the std::shared_ptr; the FDWrapper destructor calls close() when the refcount goes to zero. More...
 
void close ()
 Close the underlying file descriptor. More...
 
FileDescriptor duplicate () const
 Copy a FileDescriptor explicitly, increasing the FDWrapper refcount. More...
 
std::string read (const size_t limit=std::numeric_limits< size_t >::max())
 Read up to limit bytes. More...
 
void read (std::string &str, const size_t limit=std::numeric_limits< size_t >::max())
 Read up to limit bytes into str (caller can allocate storage) More...
 
void set_blocking (const bool blocking_state)
 Set blocking(true) or non-blocking(false) More...
 
size_t write (BufferViewList buffer, const bool write_all=true)
 Write a buffer (or list of buffers), possibly blocking until all is written. More...
 
size_t write (const char *str, const bool write_all=true)
 Write a string, possibly blocking until all is written. More...
 
size_t write (const std::string &str, const bool write_all=true)
 Write a string, possibly blocking until all is written. More...
 
int fd_num () const
 underlying descriptor number More...
 
bool eof () const
 EOF flag state. More...
 
bool closed () const
 closed flag state More...
 
unsigned int read_count () const
 number of reads More...
 
unsigned int write_count () const
 number of writes More...
 
 FileDescriptor (const FileDescriptor &other)=delete
 copy construction is forbidden More...
 
FileDescriptoroperator= (const FileDescriptor &other)=delete
 copy assignment is forbidden More...
 
 FileDescriptor (FileDescriptor &&other)=default
 move construction is allowed More...
 
FileDescriptoroperator= (FileDescriptor &&other)=default
 move assignment is allowed More...
 

Private Member Functions

 TCPSpongeSocket (std::pair< FileDescriptor, FileDescriptor > data_socket_pair, AdaptT &&datagram_interface)
 Construct LocalStreamSocket fds from socket pair, initialize eventloop. More...
 
void _initialize_TCP (const TCPConfig &config)
 Set up the TCPConnection and the event loop. More...
 
void _tcp_loop (const std::function< bool()> &condition)
 Process events while specified condition is true. More...
 
void _tcp_main ()
 Main loop of TCPConnection thread. More...
 

Private Attributes

std::atomic_bool _abort {false}
 Flag used by the owner to force the TCPConnection thread to shut down. More...
 
AdaptT _datagram_adapter
 Adapter to underlying datagram socket (e.g., UDP or IP) More...
 
EventLoop _eventloop {}
 eventloop that handles all the events (new inbound datagram, new outbound bytes, new inbound bytes) More...
 
bool _fully_acked {false}
 Has the outbound data been fully acknowledged by the peer? More...
 
bool _inbound_shutdown {false}
 Has TCPSpongeSocket shut down the incoming data to the owner? More...
 
bool _outbound_shutdown {false}
 Has the owner shut down the outbound data to the TCP connection? More...
 
std::optional< TCPConnection_tcp {}
 TCP state machine. More...
 
std::thread _tcp_thread {}
 Handle to the TCPConnection thread; owner thread calls join() in the destructor. More...
 
LocalStreamSocket _thread_data
 Stream socket for reads and writes between owner and TCP thread. More...
 

Additional Inherited Members

- Protected Member Functions inherited from Socket
 Socket (const int domain, const int type)
 Construct via socket(2). More...
 
 Socket (FileDescriptor &&fd, const int domain, const int type)
 Construct from a file descriptor. More...
 
template<typename option_type >
void setsockopt (const int level, const int option, const option_type &option_value)
 Wrapper around setsockopt(2). More...
 

Detailed Description

template<typename AdaptT>
class TCPSpongeSocket< AdaptT >

Multithreaded wrapper around TCPConnection that approximates the Unix sockets API.

This class involves the simultaneous operation of two threads.

One, the "owner" or foreground thread, interacts with this class in much the same way as one would interact with a TCPSocket: it connects or listens, writes to and reads from a reliable data stream, etc. Only the owner thread calls public methods of this class.

The other, the "TCPConnection" thread, takes care of the back-end tasks that the kernel would perform for a TCPSocket: reading and parsing datagrams from the wire, filtering out segments unrelated to the connection, etc.

There are a few notable differences between the TCPSpongeSocket and TCPSocket interfaces:

Definition at line 21 of file tcp_sponge_socket.hh.

Constructor & Destructor Documentation

◆ TCPSpongeSocket() [1/4]

template<typename AdaptT >
TCPSpongeSocket< AdaptT >::TCPSpongeSocket ( std::pair< FileDescriptor, FileDescriptor data_socket_pair,
AdaptT &&  datagram_interface 
)
private

Construct LocalStreamSocket fds from socket pair, initialize eventloop.

Parameters
[in]data_socket_pairis a pair of connected AF_UNIX SOCK_STREAM sockets
[in]datagram_interfaceis the interface for reading and writing datagrams

Definition at line 45 of file tcp_sponge_socket.cc.

◆ TCPSpongeSocket() [2/4]

template<typename AdaptT >
TCPSpongeSocket< AdaptT >::TCPSpongeSocket ( AdaptT &&  datagram_interface)
explicit

Construct from the interface that the TCPConnection thread will use to read and write datagrams.

Parameters
[in]datagram_interfaceis the underlying interface (e.g. to UDP, IP, or Ethernet)

Definition at line 176 of file tcp_sponge_socket.cc.

◆ ~TCPSpongeSocket()

template<typename AdaptT >
TCPSpongeSocket< AdaptT >::~TCPSpongeSocket

When a connected socket is destructed, it will send a RST.

Definition at line 180 of file tcp_sponge_socket.cc.

◆ TCPSpongeSocket() [3/4]

template<typename AdaptT >
TCPSpongeSocket< AdaptT >::TCPSpongeSocket ( const TCPSpongeSocket< AdaptT > &  )
delete

◆ TCPSpongeSocket() [4/4]

template<typename AdaptT >
TCPSpongeSocket< AdaptT >::TCPSpongeSocket ( TCPSpongeSocket< AdaptT > &&  )
delete

Member Function Documentation

◆ _initialize_TCP()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::_initialize_TCP ( const TCPConfig config)
private

Set up the TCPConnection and the event loop.

Definition at line 54 of file tcp_sponge_socket.cc.

◆ _tcp_loop()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::_tcp_loop ( const std::function< bool()> &  condition)
private

Process events while specified condition is true.

Parameters
[in]conditionis a function returning true if loop should continue

Definition at line 25 of file tcp_sponge_socket.cc.

◆ _tcp_main()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::_tcp_main
private

Main loop of TCPConnection thread.

Definition at line 255 of file tcp_sponge_socket.cc.

◆ bind()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::bind ( const Address address)
delete

◆ connect()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::connect ( const TCPConfig c_tcp,
const FdAdapterConfig c_ad 
)

Connect using the specified configurations; blocks until connect succeeds or fails.

Parameters
[in]c_tcpis the TCPConfig for the TCPConnection
[in]c_adis the FdAdapterConfig for the FdAdapter

Definition at line 206 of file tcp_sponge_socket.cc.

◆ listen_and_accept()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::listen_and_accept ( const TCPConfig c_tcp,
const FdAdapterConfig c_ad 
)

Listen and accept using the specified configurations; blocks until accept succeeds or fails.

Parameters
[in]c_tcpis the TCPConfig for the TCPConnection
[in]c_adis the FdAdapterConfig for the FdAdapter

Definition at line 234 of file tcp_sponge_socket.cc.

◆ local_address()

template<typename AdaptT >
Address TCPSpongeSocket< AdaptT >::local_address ( ) const
delete

◆ operator=() [1/2]

template<typename AdaptT >
TCPSpongeSocket& TCPSpongeSocket< AdaptT >::operator= ( const TCPSpongeSocket< AdaptT > &  )
delete

◆ operator=() [2/2]

template<typename AdaptT >
TCPSpongeSocket& TCPSpongeSocket< AdaptT >::operator= ( TCPSpongeSocket< AdaptT > &&  )
delete

◆ peer_address()

template<typename AdaptT >
Address TCPSpongeSocket< AdaptT >::peer_address ( ) const
delete

◆ set_reuseaddr()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::set_reuseaddr ( )
delete

◆ wait_until_closed()

template<typename AdaptT >
void TCPSpongeSocket< AdaptT >::wait_until_closed

Close socket, and wait for TCPConnection to finish

Note
Calling this function is only advisable if the socket has reached EOF, or else may wait foreever for remote peer to close the TCP connection.

Definition at line 194 of file tcp_sponge_socket.cc.

Member Data Documentation

◆ _abort

template<typename AdaptT >
std::atomic_bool TCPSpongeSocket< AdaptT >::_abort {false}
private

Flag used by the owner to force the TCPConnection thread to shut down.

Definition at line 50 of file tcp_sponge_socket.hh.

◆ _datagram_adapter

template<typename AdaptT >
AdaptT TCPSpongeSocket< AdaptT >::_datagram_adapter
private

Adapter to underlying datagram socket (e.g., UDP or IP)

Definition at line 27 of file tcp_sponge_socket.hh.

◆ _eventloop

template<typename AdaptT >
EventLoop TCPSpongeSocket< AdaptT >::_eventloop {}
private

eventloop that handles all the events (new inbound datagram, new outbound bytes, new inbound bytes)

Definition at line 36 of file tcp_sponge_socket.hh.

◆ _fully_acked

template<typename AdaptT >
bool TCPSpongeSocket< AdaptT >::_fully_acked {false}
private

Has the outbound data been fully acknowledged by the peer?

Definition at line 56 of file tcp_sponge_socket.hh.

◆ _inbound_shutdown

template<typename AdaptT >
bool TCPSpongeSocket< AdaptT >::_inbound_shutdown {false}
private

Has TCPSpongeSocket shut down the incoming data to the owner?

Definition at line 52 of file tcp_sponge_socket.hh.

◆ _outbound_shutdown

template<typename AdaptT >
bool TCPSpongeSocket< AdaptT >::_outbound_shutdown {false}
private

Has the owner shut down the outbound data to the TCP connection?

Definition at line 54 of file tcp_sponge_socket.hh.

◆ _tcp

template<typename AdaptT >
std::optional<TCPConnection> TCPSpongeSocket< AdaptT >::_tcp {}
private

TCP state machine.

Definition at line 33 of file tcp_sponge_socket.hh.

◆ _tcp_thread

template<typename AdaptT >
std::thread TCPSpongeSocket< AdaptT >::_tcp_thread {}
private

Handle to the TCPConnection thread; owner thread calls join() in the destructor.

Definition at line 45 of file tcp_sponge_socket.hh.

◆ _thread_data

template<typename AdaptT >
LocalStreamSocket TCPSpongeSocket< AdaptT >::_thread_data
private

Stream socket for reads and writes between owner and TCP thread.

Definition at line 24 of file tcp_sponge_socket.hh.


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