doc: Add comments to mp.Context PassField function on updating g_thread_context

Author: ryanofsky

include/mp/proxy-types.h

@@ -126,6 +126,23 @@ auto PassField(Priority<1>, TypeList<>, ServerContext& server_context, const Fn&
                 Context::Reader context_arg = Accessor::get(params);
                 ServerContext server_context{server, call_context, req};
                 {
+                    // Before invoking the function, store a reference to the
+                    // callbackThread provided by the client in the
+                    // thread_local.request_threads map. This way, if this
+                    // server thread needs to execute any RPCs that call back to
+                    // the client, they will happen on the same client thread
+                    // that is waiting for this function, just like what would
+                    // happen if this were a normal function call made on the
+                    // local stack.
+                    //
+                    // If the request_threads map already has an entry for this
+                    // connection, it will be left unchanged, and it indicates
+                    // that the current thread is an RPC client thread which is
+                    // in the middle of an RPC call, and the current RPC call is
+                    // a nested call from the remote thread handling that RPC
+                    // call. In this case, the callbackThread value should point
+                    // to the same thread already in the map, so there is no
+                    // need to update the map.
                     auto& request_threads = g_thread_context.request_threads;
                     auto request_thread = request_threads.find(server.m_context.connection);
                     if (request_thread == request_threads.end()) {
@@ -136,8 +153,11 @@ auto PassField(Priority<1>, TypeList<>, ServerContext& server_context, const Fn&
                                         /* destroy_connection= */ false))
                                 .first;
                     } else {
-                        // If recursive call, avoid remove request_threads map
-                        // entry in KJ_DEFER below.
+                        // The requests_threads map already has an entry for
+                        // this connection, so this must be a recursive call.
+                        // Avoid modifying the map in this case by resetting the
+                        // request_thread iterator, so the KJ_DEFER statement
+                        // below doesn't do anything.
                         request_thread = request_threads.end();
                     }
                     KJ_DEFER(if (request_thread != request_threads.end()) request_threads.erase(request_thread));