fix: update compio docs

Author: Berrysoft

content/docs/compio/buffers.md

@@ -4,13 +4,13 @@ Crate `compio-buf` is fundamental to `compio`. It provides abstractions for diff
 
 ## Buffer traits
 
-The trait `IoBuf` is the abstract of read-only buffers. Trait `IoBufMut` provides writing methods in addition, but it doesn't support extending the buffer. Therefore, even `Vec` implements `IoBufMut`, a write operation can only write into the allocated space, but cannot extend the vector automatically.
+The trait `IoBuf` is the abstract of read-only buffers. Trait `IoBufMut` provides writing methods in addition, and supports extending the buffer. A write operation can only write into the allocated space, but cannot extend the vector automatically.
 
 `IoBuf` & `IoBufMut` represent owned buffers. The IO operations always require the ownership of a buffer to avoid potential race conditions. Although the traits implement for arrays `[u8; N]`, it's not a good idea to use them as buffer type, because the move operation of them is relatively slow. Use `Vec<u8>` or `Box<[u8]>` instead.
 
 ## Slicing
 
-Sometimes an owned slice of the buffer is needed. `IoBuf::slice` provides such convenience. It creates a slice which owns the buffer, and the buffer could be retrieved by `<Slice as IntoInner>::into_inner`.
+Sometimes an owned slice of the buffer is needed. `IoBuf::slice` provides such convenience. It creates a slice which owns the buffer, and the buffer could be retrieved by `<Slice as IntoInner>::into_inner`. `IoBufMut::uninit` provides similar functionalities, but it represents only the uninitialized part of the buffer.
 
 ## Vectored buffers
 

content/docs/compio/dispatcher.md

@@ -28,3 +28,6 @@ for _i in 0..CLIENT_NUM {
 while handles.next().await.is_some() {}
 dispatcher.join().await.unwrap();
 ```
+
+## An optional solution
+The dispatcher is not the only solution to multi-threading webservers. `SO_REUSEADDR` or `SO_REUSEPORT` might be more efficient.

content/docs/compio/driver.md

@@ -22,4 +22,4 @@ The `Proactor` provides a simple cancellation mechanism. The cancellation of an
 
 ## Shared FDs
 
-"File descriptors" in `compio` represents the file descriptors on Unix and handles on Windows. When the driver is holding the operations, it should also hold the reference of the related fds. Therefore, all fds are wrapped inside an `Arc`. When a file or socket is cloned, the inner `Arc` is cloned, rather than duplicating (e.g., with `dup`) the fds or handles. When the method `close` is called on a file or socket, the future will wait for all related operations to complete. Therefore, it's not a good idea to close a cloned file or socket.
+"File descriptors" in `compio` represents the file descriptors on Unix and handles on Windows. When the driver is holding the operations, it should also hold the reference of the related fds. Therefore, all fds are wrapped inside an `Rc`/`Arc`, depending on the feature `"sync"`. When a file or socket is cloned, the inner `Rc`/`Arc` is cloned, rather than duplicating (e.g., with `dup`) the fds or handles. When the method `close` is called on a file or socket, the future will wait for all related operations to complete. Therefore, it's not a good idea to close a cloned file or socket.

content/docs/compio/driver/io-uring.md

@@ -1,14 +1,14 @@
 # io-uring
 
-The io-uring driver requires a Linux 5.19+ kernel. The kernel version limitation is from the oldest supported Ubuntu version.
-
 Some operations require a newer kernel, so they are hidden behind feature gates.
 
 | feature           | description                         |
 | ----------------- | ----------------------------------- |
 | `io-uring-cqe32`  | Enable large completion queue entry |
 | `io-uring-sqe128` | Enable large submission queue entry |
 
-If a feature is enabled but the kernel doesn't support it, the behavior depends on whether `polling` feature is also enabled. If `polling` is not enabled, the driver will continue using io-uring regardless of the kernel support. Or `polling` will be used as a fallback.
+If the kernel doesn't support these features, the driver will not fallback to the polling driver.
+
+If the kernel doesn't support the opcode to be submitted, the driver will fallback to a blocking operation.
 
 As io-uring is a bounded ring, possibly there is a case that the queues are full. The kernel is responsible to decide whether to discard the entries or report it to the user.

content/docs/compio/driver/polling.md

@@ -1,19 +1,19 @@
 # polling
 
-`polling` crate is a subproject of `smol`. It provides a unified wrapper for the reactors on most platforms. Therefore, it is used on platforms other than Windows. On Linux, it is an option if io-uring is not available. When the user enables both `"io-uring"` and `"polling"`, a "fusion" driver is used and responsible for deciding which one to use in runtime.
+`polling` crate is a subproject of `smol`. It provides a unified wrapper for the reactors on most platforms. Therefore, it is used on platforms other than Windows. On Linux, it is an option if io-uring is not available. When the user enables both `"io-uring"` and `"polling"`, a "fusion" driver is used and responsible for deciding which one to use in runtime. You are able to specify the exact driver to use in the `ProactorBuilder`.
 
 Frankly, there is no real async operations in a reactor. The socket IO operations are non-blocking, but the data copying still takes time. The blocking operations are spawned to the thread pool.
 
 ## What about AIO?
 
 The POSIX standard leaves no way to interact the AIO operations with polling interfaces.
 
-## FreeBSD
+### FreeBSD
 
 FreeBSD provides extensions to post AIO events to kqueue. There are some known issues:
 * Some filesystems don't support AIO. `compio` fallbacks to blocking call if the AIO method returns `EOPNOTSUPP`.
 * The process-wide AIO queue is limited. If the queue is full, users cannot add new AIO requests unless one control block is removed by `aio_return`. In that case, `compio` fallbacks to blocking call.
 
-## Illumos & Solaris
+### Illumos & Solaris
 
 Solarish systems provides extensions to post AIO events to an event port. However, it doesn't support `aio_readv` or `aio_writev`. Therefore, `compio` fallbacks to `aio_read` & `aio_write` for files on solarish systems.

content/docs/compio/io.md

@@ -34,8 +34,12 @@ assert_eq!(read_len, buffer.len());
 
 ## Managed buffer pool
 
-`AsyncReadManaged` and `AsyncReadManagedAt` provide methods to read data with a buffer pool. The buffer pool itself, or the runtime, is responsible for selecting and filling in the suitable buffer. It is specially optimized when using `compio` with `"io-uring"` feature enabled.
+`AsyncReadManaged` and `AsyncReadManagedAt` provide methods to read data with a buffer pool. The buffer pool itself, or the runtime, is responsible for selecting and filling in the suitable buffer. It is specially optimized when using `compio` with io-uring driver enabled.
 
 ## Compatible helpers
 
 Mod `compio::io::compat` provides `SyncStream` and `AsyncStream` for compatibility usages. `SyncStream` implements `std::io::{Read, Write}`, and will return error with `WouldBlock` if the inner buffer should be updated manually. `AsyncStream` wraps `SyncStream` and implements `AsyncRead` & `AsyncWrite` of `futures`.
+
+## Framed IO
+
+TODO

content/docs/compio/net.md

@@ -1,5 +1,5 @@
 # Networking
 
-`compio-net` provides most networking affairs. TCP, UDP, Unix sockets are supported. The TLS support is in `compio-tls`, while QUIC support is in `compio-quic`. For high level HTTP support, see `cyper`.
+`compio-net` provides most networking affairs. TCP, UDP, Unix sockets are supported. The TLS support is in `compio-tls`, the QUIC support is in `compio-quic`, and the WebSocket support is in `compio-ws`. For high level HTTP support, see `cyper`.
 
 Sockets in `compio` expose completion-based APIs. If it is too confusing to use, `PollFd` is provided for all kinds of socket resources, and exposes ready-based APIs.

content/docs/compio/net/sockets.md

@@ -10,9 +10,9 @@ A client can simply use `TcpStream::connect` to connect to the remote listener.
 
 See the introduction of [`File::close`](../fs/file) for closing the sockets.
 
-## TCP options
+## Socket options
 
-`TcpListener::bind_with_options`, `TcpStream::connect_with_options` and `TcpStream::bind_and_connect_with_options` accept `TcpOpts` to specify TCP options on creation.
+`*Listener::bind_with_options`, `*Listener::accept_with_options`, `*Stream::connect_with_options` and `TcpStream::bind_and_connect_with_options` accept `SocketOpts` to specify options on creation.
 
 ## Dual-stack support
 
@@ -24,4 +24,4 @@ Windows _does_ support Unix sockets, with some limitations. A Unix socket on Win
 
 ## Control messages of UDP sockets
 
-TODO
+There are `send_msg*` and `recv_msg*` methods in `UdpSocket`. They retrieve ancillary data as raw buffers. The users are responsible to align the buffer correctly.

content/docs/compio/ws.md

@@ -0,0 +1,3 @@
+# WebSocket
+
+`compio::ws` contains adapters for `tungstenite`. It is almost the same as `tokio-tungstenite`.

content/docs/summary.ts

@@ -36,7 +36,8 @@ const compio: Section[] = [
   ['Signal', '/docs/compio/signal'],
   ['Process', '/docs/compio/process'],
   ['TLS', '/docs/compio/tls'],
-  // [['QUIC', 'compio/quic'], [['HTTP 3', 'compio/quic/http3']]], // TODO(@Berrysoft): Write this
+  ['WebSocket', "/docs/compio/ws"]
+  // [['QUIC', 'compio/quic'], [['HTTP 3', 'compio/quic/http3']]], // TODO(@AsakuraMizu): Write this
 ]
 
 const cyper: Section[] = [