From 9377a99b5666703d34f9cc160d7f6380a19dea84 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Sat, 12 Oct 2019 01:39:59 +0200
Subject: [PATCH] fixup! fixup! dgram: make UDPWrap more reusable

---
 src/udp_wrap.h | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/udp_wrap.h b/src/udp_wrap.h
index 658bd9eca4..997053a518 100644
--- a/src/udp_wrap.h
+++ b/src/udp_wrap.h
@@ -34,16 +34,36 @@ namespace node {
 
 class UDPWrapBase;
 
+// A listener that can be attached to an `UDPWrapBase` object and generally
+// manages its I/O activity. This is similar to `StreamListener`.
 class UDPListener {
  public:
   virtual ~UDPListener();
+
+  // Called right before data is received from the socket. Must return a
+  // buffer suitable for reading data into, that is then passed to OnRecv.
   virtual uv_buf_t OnAlloc(size_t suggested_size) = 0;
+
+  // Called right after data is received from the socket, and includes
+  // information about the source address. If `nread` is negative, an error
+  // has occurred, and it represents a libuv error code.
   virtual void OnRecv(ssize_t nread,
                       const uv_buf_t& buf,
                       const sockaddr* addr,
                       unsigned int flags) = 0;
+
+  // Called when an asynchronous request for writing data is created.
+  // The `msg_size` value contains the total size of the data to be sent,
+  // but may be ignored by the implementation of this Method.
+  // The return value is later passed to OnSendDone.
   virtual ReqWrap<uv_udp_send_t>* CreateSendWrap(size_t msg_size) = 0;
+
+  // Called when an asynchronous request for writing data has finished.
+  // If status is negative, an error has occurred, and it represents a libuv
+  // error code.
   virtual void OnSendDone(ReqWrap<uv_udp_send_t>* wrap, int status) = 0;
+
+  // Optional callback that is called after the socket has been bound.
   virtual void OnAfterBind() {}
 
   inline UDPWrapBase* udp() const { return wrap_; }
@@ -59,13 +79,26 @@ class UDPWrapBase {
   static constexpr int kUDPWrapBaseField = 1;
 
   virtual ~UDPWrapBase();
+
+  // Start emitting OnAlloc() + OnRecv() events on the listener.
   virtual int RecvStart() = 0;
+
+  // Stop emitting OnAlloc() + OnRecv() events on the listener.
   virtual int RecvStop() = 0;
+
+  // Send a chunk of data over this socket. This may call CreateSendWrap()
+  // on the listener if an async transmission is necessary.
   virtual ssize_t Send(uv_buf_t* bufs,
                        size_t nbufs,
                        const sockaddr* addr) = 0;
+
+  // Stores the sockaddr for the peer in `name`.
   virtual int GetPeerName(sockaddr* name, int* namelen) = 0;
+
+  // Stores the sockaddr for the local socket in `name`.
   virtual int GetSockName(sockaddr* name, int* namelen) = 0;
+
+  // Returns an AsyncWrap object with the same lifetime as this object.
   virtual AsyncWrap* GetAsyncWrap() = 0;
 
   void set_listener(UDPListener* listener);