xynet

Experimental C++ network library based on io_uring and coroutine. This project is developed for understanding and practice C++20 new features(ranges, coroutine) and new Linux I/O API io_uring.

Features

Header only
Based on io_uring, the new Linux asynchronous I/O API
Based on C++20 coroutine
file_descriptor is designed in the CRTP Mixin pattern, all operations(recv, send, listen...) are modularized and thus optional.
buffer_sequence is designed to be compatible with C++20 std::span
like C++17 <filesystem>, support error handling in both std::error_code and exception
coroutine part is based on Lewis Baker's cppcoro, modified so that it could compile using gcc10.
Efficient:
- Few dynamic allocation: most of the allocations are for the coroutine stack itself.
- Few system calls compared with epoll based libraries: All asynchronous operations are submitted and reaped through io_uring by a single system call.

Requirements

Compiler: GCC10.0.1 (or later)
Linux Kernel: 5.2 (or later)
Liburing: 0.5(or later)
OpenSSL: for the SHA-1 in websocket(will be removed later)

Example

RFC864 Character Generator Protocol: chargen.cpp
RFC867 Daytime Protocol: daytime.cpp
RFC863 Discard Protocol: discard.cpp
RFC862 Echo Protocol: echo.cpp
RFC868 Time Protocol: time.cpp
boost::asio ping-pong performance test: pingpong
ttcp: ttcp
boost::asio chatroom: chat
websocket discard: websocket_discard.cpp
websocket echo: websocket_echo.cpp
boost::beast websocket chatroom: websocket_chat.cpp

Usage

file_descriptor
```
template <template <typename...> typename ... Modules>
class file_descriptor<detail::module_list<Modules ...>>
  : public file_descriptor_base
  , public Modules<file_descriptor<detail::module_list<Modules ...>>>...
{};
```
file_descriptor is a handler that has unique ownership of file descriptor, like std::unique_ptr.
- move-only,
- RAII. ::close() is called in its destructor if the underlying file descriptor is valid.
- Modularized: Modules are interfaces that are mixin'ed into the base class. Modules access file_descriptor by static polymorphism, i.e. cast this into the base class type.
- default constructor will initialize the underlying file descriptor to be an invalid one.
- Mixin'ed modules use set() and get() to work with the file_descriptor.

socket_t

using socket_t = file_descriptor
<
  detail::module_list
  <
    socket_init,
    address,
    operation_shutdown,
    operation_set_options,
    operation_bind,
    operation_listen,
    operation_accept,
    operation_connect,
    operation_send,
    operation_recv,
    operation_close
  >
>;

convenient type alias that has all modules for socket. You can define you own type alias. For example, an acceptor does not need to do send or recv.

using acceptor_t = file_descriptor
<
  detail::module_list
  <
    socket_init,
    operation_set_options,
    operation_bind,
    operation_listen,
    operation_accept
  >
>;

buffer_sequence and const_buffer_sequence

buffer_sequence takes a sequences of Containers which satisfy the concept std::ranges::contiguous_range then transform them into iovec.

buffer_sequence could be constructed using:
```
template<typename... Containers>
buffer_sequence(Containers&&... containers)
```
where Containers could be
- std::span<std::byte, size or std::dynamic_extent>
- std::span<Ts, size or std::dynamic_extent>
- contiguous ranges that are writable
or
```
template<typename BufferRange>
requires std::ranges::viewable_range<BufferRange&>
         && std::ranges::contiguous_range<std::ranges::range_value_t<BufferRange>>
buffer_sequence(BufferRange& buffer_range)
```
where BufferRange is a range of contiguous ranges. Notice that, different from the former one, iovecs are stored in a std::vector where dynamic allocation is inevitable.
Modules

All modules support error handling by
- std::error_code: by passing an lvalue reference of std::error_code (like C++17 <filesystem>), should there be an error, the lvalue reference passed will assign with a new error_code, otherwise, it will be clear().
- exception. An std::system_error constructed by the reason encapsulated in a std::error_code will be throwed if there is an error.
- socket_init
  - init(), init(std::erro_code& error) create a IPv4/TCP socket and set the file_descriptor with the file_descriptor returned form ::socket().
- address
  
  the size of file_descriptor will increase if this module is used.
  
  Getters and setters are provided: set_local_address(const socket_address& address), set_peer_address(const socket_address& address), get_local_address(), get_peer_address(). Moudles like operation_accept, operation_connect , will set the address on success.
synchronous operation modules
- operation_shutdown
  
  shutdown(int how = SHUTWR), shutdown(int how, std::error_code& error), shutdown(std::error_code& error)
- operation_bind
  
  bind the socket to a given address. If module address is used, set the local address on success. If bind with socket_address{0}, then a random port will be assigned and the local address will also be set on success.
  
  bind(const socket_address& address), bind(const socket_address& address, std::error_code& error)
- operation_set_options
  
  call ::setsockopt.
  
  void setsockopt(int level, int optname, const void* optval, socklen_t optlen, std::error_code& error), void setsockopt(int level, int optname, const void* optval, socklen_t optlen), void reuse_address(std::error_code& error), void reuse_address()
- operation_listen
  
  put the socket into listen state listen(int backlog = SOMAXCONN), listen(int backlog, std::error_code& error), listen(std::error_code& error).
asynchronous operation modules

all asynchronous operations provides an optional argument duration to impose a timeout.
- operation_accept
```
template<typename F2, typename... Args> [[nodiscard]]
decltype(auto) accept(F2& peer_socket, Args&&... args) noexcept
```
- peer_socket The socket into which the new connection will be accpeted.
  1. Args is void: The awaiter returned by the function will throw exception to report the error. A std::system_error constructed with the corresponding std::error_code will be throwed if the accept operation is failed after being co_await'ed.
  2. Args is a Duration, i.e. std::chrono::duration<Rep, Period>. This duration will be treated as the timeout for the operation. If the operation does not finish within the given duration, the operation will be canneled and an error_code (std::errc::operation_canceled) will be returned.
  3. Args is an lvalue reference of a std::error_code The awaiter returned by the function will use std::error_code to report the error. Should there be an error in the operation, the std::error_code passed by lvalue reference will be reset. Otherwise, it will be clear.
  4. Args are first a Duration, second an lvalue reference of a std::error_code The operation will have the features described in 2 and 3.
- operation_connect
```
template<typename... Args> [[nodiscard]]
decltype(auto) connect(const socket_address& address, Args&&... args) noexcept
```
address: the address with which the connection will be established. args: same as args desribed in operation_accept
- operation_close
This operation will read from the socket until it reads a 0(eof). Then it will call close(2) on the socket.
```
template<typename... Args>
[[nodiscard]]
decltype(auto) close(Args&&... args) noexcept 
```
args: same as args desribed in operation_accept
- operation_recv
  
  recv([std::error_code& error], [Duration&& duration], Args&&... args) where args will be forwarded to the constructor of buffer_sequence.
  - The buffers will be filled with the same order as the order they were in the lvalue reference of a viewable range or the order they were in args.
  - The operation will finish if there is an error(including the socket reads EOF) or all the buffers are filled. That is, it may use recvmsg(2) more than once.
  - After the operation is co_await'ed and then finishes, it will return the bytes transferred.
  recv_some([std::error_code& error], [Duration&& duration], Args&&... args) where args will be forwarded to the constructor of buffer_sequence.
  
  this awaiter will resume the coroutine after the first recv operation finished, regardless of whether the buffers are filled up or not.
- operation_send
  
  recv([std::error_code& error], [Duration&& duration], Args&&... args) where args will be forwarded to the constructor of const_buffer_sequence

xuanyi-fu/xynet

xynet

Features

Requirements

Example

Usage