More thoroughly document how mojom.NavigationClient gets reused
RenderFrameImpl maintains a mojom.NavigationClient implementation that
acts as a:
1.) "Request" navigation client:
For navigations on a target frame where the initiator is local.
This is used to cancel navigations that have been sent to the
browser, and to listen for when the browser "drops" navigations
2.) "Commit" navigation client:
Which the browser uses to commit navigations to.
Sometimes the same navigation client implementation is used as both, and this CL more thoroughly documents when and how this happens.
Change-Id: Ib3192d1b0f911839cd8a9d9119670cebbc4e1281
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3835467
Reviewed-by: Rakina Zata Amni <rakina@chromium.org>
Commit-Queue: Dominic Farolino <dom@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1036655}
diff --git a/content/renderer/render_frame_impl.h b/content/renderer/render_frame_impl.h
index ebea3f5fc..c8e8225 100644
--- a/content/renderer/render_frame_impl.h
+++ b/content/renderer/render_frame_impl.h
@@ -1285,7 +1285,21 @@
//
// If a navigation will commit in the same RenderFrameImpl that owns the
// request NavigationClient, the request NavigationClient will be reused as
- // the commit NavigationClient.
+ // the commit NavigationClient. The way this works is:
+ // 1.) RenderFrameHostImpl::BeginNavigation() accepts an always-bound remote
+ // to the RenderFrameImpl's `navigation_client_impl_`.
+ // 2.) In `NavigationRequest::ctor()`, the request consumes the
+ // NavigationClient remote, and `NavigationRequest::SetNavigationClient()`
+ // assigns `NavigationRequest::request_navigation_client_` to it.
+ // 3.) Eventually, `NavigationRequest` picks a `RenderFrameHostImpl` to commit
+ // to. In `NavigationRequest::CommitNavigation()`, the request needs to
+ // set its `commit_navigation_client_` to the `NavigationClient`
+ // implementation in the target RenderFrameImpl. If we detect that the
+ // navigation will commit to the same frame that
+ // `NavigationRequest::request_navigation_client_` points to, then the
+ // browser will reuse the request navigation client as the commit one.
+ // Otherwise, it requests a *new* client from the renderer, to act as the
+ // target RenderFrameImpl's `NavigationClient`.
//
// ## Navigation Cancellation ##
// Cancellation is signalled by closing the NavigationClient message pipe.
