Add documentation to asocket
Asocket is not straight forward to understand. This CL adds a bit of
documentation and group fields by type of socket they belong to.
It pave the way to the next CL which turns asocket into a class
leverating polymorphism.
Bug: NA
Test: NA
Change-Id: I8f460698a9b073d1172ff6e44e2855eb88ba87b7
diff --git a/socket.h b/socket.h
index a8d0793..d8a91a8 100644
--- a/socket.h
+++ b/socket.h
@@ -31,16 +31,41 @@
class atransport;
/* An asocket represents one half of a connection between a local and
- * remote entity. A local asocket is bound to a file descriptor. A
- * remote asocket is bound to the protocol engine.
+ remote entity. A local asocket is bound to a file descriptor. A
+ remote asocket is bound to the protocol engine.
+
+ Example (two local_sockets) :
+
+ ASOCKET(THIS)
+ ┌────────────────────────────────────────────────┐
+┌──┐ write(3) │ ┌─────┐ enqueue() │
+│ │◄─────────┼──┤Queue├─────────────◄────────────┐ │
+│fd│ │ └─────┘ ▲ │
+│ ├──────────►─────────────────┐ │ │
+└──┘ read(3) └─────────────────┼─────────────────┼────────────┘
+ outgoing │ │ incoming
+ ┌─────────────────▼─────────────────▲────────────┐ read(3) ┌──┐
+ │ │ └────────────┼─────────◄─┤ │
+ │ │ ┌─────┐ │ │fd│
+ │ └─────────────────────►│Queue├─┼─────────►─┤ │
+ │ enqueue() └─────┘ │ write(3) └──┘
+ └────────────────────────────────────────────────┘
+ ASOCKET(PEER)
+
+ Note that sockets can be peered regardless of their kind. A remote socket can be peered with
+ a smart socket, a local socket can be peered with a remote socket and so on.
*/
struct asocket {
/* the unique identifier for this asocket
*/
unsigned id = 0;
+ // Start Local socket fields
+ // TODO: move all the local socket fields together
+
/* flag: set when the socket's peer has closed
* but packets are still queued for delivery
+ * TODO: This should be a boolean.
*/
int closing = 0;
@@ -53,6 +78,8 @@
*/
int exit_on_close = 0;
+ // End Local socket fields
+
// the asocket we are connected to
asocket* peer = nullptr;
@@ -86,22 +113,26 @@
size_t get_max_payload() const;
- // Local socket fields
// TODO: Make asocket an actual class and use inheritance instead of having an ever-growing
// struct with random use-specific fields stuffed into it.
+
+ // Start Local socket fields
fdevent* fde = nullptr;
int fd = -1;
// Queue of data that we've received from our peer, and are waiting to write into fd.
IOVector packet_queue;
+ // End Local socket fields
// The number of bytes that have been acknowledged by the other end if delayed_ack is available.
// This value can go negative: if we have a MAX_PAYLOAD's worth of bytes available to send,
// we'll send out a full packet.
std::optional<int64_t> available_send_bytes;
+ // Start Smart socket fields
// A temporary buffer used to hold a partially-read service string for smartsockets.
std::string smart_socket_data;
+ // End Smart socket fields
};
asocket *find_local_socket(unsigned local_id, unsigned remote_id);