Support frame tree propagation between renderers in the same browsing instance.

content/common/view_messages.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // IPC messages for page rendering.
 // Multiply-included message file, hence no include guard.
 
 #include "base/process.h"
 #include "base/shared_memory.h"
 #include "content/common/content_export.h"
@@ skipping 554 matching lines @@
   // to convert them to pixels.
   IPC_STRUCT_MEMBER(float, scale_factor)
 IPC_STRUCT_END()
 
 IPC_STRUCT_BEGIN(ViewMsg_PostMessage_Params)
   // The serialized script value.
   IPC_STRUCT_MEMBER(string16, data)
 
   // When sent to the browser, this is the routing ID of the source frame in
   // the source process.  The browser replaces it with the routing ID of the
-  // equivalent (swapped out) frame in the destination process.  Set to
-  // MSG_ROUTING_NONE if the source frame isn't supported (e.g., subframes).
+  // equivalent (swapped out) frame in the destination process.
   IPC_STRUCT_MEMBER(int, source_routing_id)
+  // The identifier of the source frame in the source process.
+  IPC_STRUCT_MEMBER(int, source_frame_id)
+
+  // The full set of identifiers to uniquely descirbe the target frame. See

[Charlie Reis, 2012/08/22 22:08:34]

nit: describe

[nasko, 2012/08/23 21:55:53]

Done.

+  // the comment on ViewMsg_FrameTreeUpdated for details.
+  IPC_STRUCT_MEMBER(int, target_process_id)
+  IPC_STRUCT_MEMBER(int, target_routing_id)
+  IPC_STRUCT_MEMBER(int, target_frame_id)
 
   // The origin of the source frame.
   IPC_STRUCT_MEMBER(string16, source_origin)
 
   // The origin for the message's target.
   IPC_STRUCT_MEMBER(string16, target_origin)
 IPC_STRUCT_END()
 
 IPC_STRUCT_BEGIN(ViewHostMsg_DidFailProvisionalLoadWithError_Params)
   // The frame ID for the failure report.
@@ skipping 443 matching lines @@
 IPC_MESSAGE_ROUTED4(ViewMsg_ScriptEvalRequest,
                     string16,  /* frame_xpath */
                     string16,  /* jscript_url */
                     int,  /* ID */
                     bool  /* If true, result is sent back. */)
 
 // Posts a message from a frame in another process to the current renderer.
 IPC_MESSAGE_ROUTED1(ViewMsg_PostMessageEvent,
                     ViewMsg_PostMessage_Params)
 
+// Sends a JSON serialized frame tree to render processes along with the
+// process id and route id of the source renderer.
+//
+// This message must be send to swapped out renderers every time the browser

[Charlie Reis, 2012/08/22 22:08:34]

nit: send -> sent

[nasko, 2012/08/23 21:55:53]

Done.

+// receives a ViewHostMsg_FrameTreeUpdated message.
+//
+
+

[Charlie Reis, 2012/08/22 22:08:34]

nit: Remove blank lines.

[nasko, 2012/08/23 21:55:53]

Done.

+IPC_MESSAGE_ROUTED3(ViewMsg_UpdateFrameTree,
+                    int, /* the child process id of the active renderer */
+                    int, /* route_id of the active renderer */
+                    std::string /* json encoded frame tree */)
+
 // Request for the renderer to evaluate an xpath to a frame and insert css
 // into that frame's document. See ViewMsg_ScriptEvalRequest for details on
 // allowed xpath expressions.
 IPC_MESSAGE_ROUTED2(ViewMsg_CSSInsertRequest,
                     string16,  /* frame_xpath */
                     std::string  /* css string */)
 
 // External popup menus.
 #if defined(OS_MACOSX)
 IPC_MESSAGE_ROUTED1(ViewMsg_SelectPopupMenuItem,
@@ skipping 1134 matching lines @@
 // (according to the value of is_hung). The browser can give the user the
 // option of killing the plugin.
 IPC_MESSAGE_ROUTED3(ViewHostMsg_PepperPluginHung,
                     int /* plugin_child_id */,
                     FilePath /* path */,
                     bool /* is_hung */)
 
 // Screen was rotated. Dispatched to the onorientationchange javascript API.
 IPC_MESSAGE_ROUTED1(ViewMsg_OrientationChangeEvent,
                     int /* orientation */)
+
+// Chrome allows JavaScript calls to be routed across process boundaries. To
+// achive this, each active renderer in the source process has a swapped out

[Charlie Reis, 2012/08/22 22:08:34]

nit: achieve
nit: renderer -> RenderView
(Same below.  In general, "renderer" means the process, which may have multiple
RenderViews.)

[nasko, 2012/08/23 21:55:53]

Done.

+// mirror in the destination process. The active renderer and its mirror need to

[Charlie Reis, 2012/08/22 22:08:34]

Hmm, we haven't been using this "mirror" term before, but I suppose it's apt. 
Please put the first occurrence in quotes.

Also, we're calling this target instead of destination in other places.  Let's
be consistent with one or the other.

[nasko, 2012/08/23 21:55:53]

Done.

+// have identical frame tree structure, so calls originating and targeting
+// subframes can be routed properly. This is achieved by each active renderer
+// sending a ViewHostMsg_FrameTreeUpdated message to the browser, which in turn
+// sends the update to the corresponding mirror renderers through the
+// ViewMsg_UpdateFrameTree.

[Charlie Reis, 2012/08/22 22:08:34]

This is a great explanation.  Since we say they "need to have identical frame
tree structure," I think we also need to note something about concurrency. 
(e.g., We use best effort to maintain these trees across processes.)

[nasko, 2012/08/23 21:55:53]

Done.

+//
+// When routing JavaScript calls across processes, the destination information
+// is kept in the renderer process instead of the browser process. This design
+// was chosen because frame ids are allocated by the renderer process. If the
+// browser was to keep a mapping of the frame ids across processes, it will

[Charlie Reis, 2012/08/22 22:08:34]

nit: will -> would

[nasko, 2012/08/23 21:55:53]

Done.

+// require an extra IPC message with the newly allocated frame ids, as a
+// response to this particular message.
+//
+// The frame tree for a renderer is serialized to JSON, so it can be sent to
+// the browser process. Each node in the tree is a DictionaryValue with three
+// properties:

[awong, 2012/08/22 22:25:47]

Since this is JSON, I'd define this in terms of JSON rather than talking bout
DictionaryValue since a "DictionaryValue" is an implementaiton detail.

[nasko, 2012/08/23 21:55:53]

Done.

+// * id - the frame identifier in this renderer
+// * name - the name of the frame, if one has been assigned
+// * subtree - a list of DictionaryValue objects for each frame that is

[Charlie Reis, 2012/08/22 22:08:34]

nit: that is a direct child

[nasko, 2012/08/23 21:55:53]

Done.

+//     direct child of the current frame. This property can be omitted if
+//     there are no direct child frames, so less data is transferred.
+//
+// This message must be sent on any events that modify the tree structure or
+// the names of any frames.
+IPC_MESSAGE_ROUTED1(ViewHostMsg_FrameTreeUpdated,
+                    std::string /* json encoded frame tree */)