Include class relationship diagrams in network stack documentation.

net/docs/life-of-a-url-request.md

 # Life of a URLRequest
 
 This document is intended as an overview of the core layers of the network
 stack, their basic responsibilities, how they fit together, and where some of
 the pain points are, without going into too much detail. Though it touches a
 bit on child processes and the content/loader stack, the focus is on net/
 itself.
 
 It's particularly targeted at people new to the Chrome network stack, but
 should also be useful for team members who may be experts at some parts of the
@@ skipping 275 matching lines @@
 ResourceLoader tells the ResourceHandlers, and the AsyncResourceHandler tells
 the ResourceDispatcher the request is complete. The RDH then deletes
 ResourceLoader, which deletes the URLRequest and ResourceHandler chain.
 
 When the HttpNetworkTransaction is being torn down, it figures out if the
 socket is reusable. If not, it tells the HttpBasicStream to close the socket.
 Either way, the ClientSocketHandle returns the socket is then returned to the
 socket pool, either for reuse or so the socket pool knows it has another free
 socket slot.
 
+### Object Relationships and Ownership
+
+A sample of the object relationships involved in the above process is
+diagramed here: 
+
+![Object Relationship Diagram for URLRequest lifetime](url_request.svg)
+
+There are a couple of points in the above diagram that do not come
+clear visually:
+
+* The method that generates the filter chain that is hung off the
+  URLRequestJob is declared on URLRequestJob, but the only current
+  implementation of it is on URLRequestHttpJob, so the generation is
+  shown as happening from that class.
+* HttpTransactions of different types are layered; i.e. a
+  HttpCache::Transaction contains a pointer to an HttpTransaction, but
+  that pointed-to HttpTransaction generally is an
+  HttpNetworkTransaction. 
 
 # Additional Topics
 
 ## HTTP Cache
 
 The HttpCache::Transaction sits between the URLRequestHttpJob and the
 HttpNetworkTransaction, and implements the HttpTransaction interface, just like
 the HttpNetworkTransaction. The HttpCache::Transaction checks if a request can
 be served out of the cache. If a request needs to be revalidated, it handles
 sending a 204 revalidation request over the network. It may also break a range
@@ skipping 105 matching lines @@
 layer pools owns are actively in use, even when the higher layer pool considers
 them idle. As a result, when a lower layer pool is at its connection limit and
 needs to make a new connection, it will ask any higher layer pools pools to
 close an idle connection if they have one, so it can make a new connection.
 
 Since sockets in the higher layer pool are also in a group in the lower layer
 pool, they must have their own distinct group name. This is needed so that, for
 instance, SSL and HTTP connections won't be grouped together in the
 TcpClientSocketPool, which the SSLClientSocketPool sits on top of.
 
+### Socket Pool Class Relationships
+
+The relationships between the important classes in the socket pools is
+shown diagrammatically for the lowest layer socket pool
+(TransportSocketPool) below. 
+
+![Object Relationship Diagram for Socket Pools](pools.svg)
+
+The ClientSocketPoolBase is a template class templatized on the class
+containing the parameters for the appropriate type of socket (in this
+case TransportSocketParams).  It contains a pointer to the
+ClientSocketPoolBaseHelper, which contains all the type-independent
+machinery of the socket pool.  
+
+When socket pools are initialized, they in turn initialize their
+templatized ClientSocketPoolBase member with an object with which it
+should create connect jobs.  That object must derive from
+ClientSocketPoolBase::ConnectJobFactory templatized by the same type
+as the ClientSocketPoolBase.  (In the case of the diagram above, that
+object is a TransportConnectJobFactory, which derives from
+ClientSocketPoolBase::ConnectJobFactory<TransportSocketParams>.)

[eroman, 2016/04/06 17:41:17]

Note that angle brackets are interpreted as HTML in markdown, so this needs to
be escaped.

Searching the document I see we have the problem higher up too, and confirmed
that on
https://chromium.googlesource.com/chromium/src/+/master/net/docs/life-of-a-ur...
it is not rendering as desired.

I expect the fix is <     > 

[eroman, 2016/04/06 18:11:07]

(Another fix would be to make it a `codeblock`, since angle brackets inside of
codeblocks is fine, but that would be inconsistent with rest of this doc)

[Randy Smith (Not in Mondays), 2016/04/06 20:57:54]

Done.

[Randy Smith (Not in Mondays), 2016/04/06 20:57:55]

Acknowledged.

+Internally, that object is wrapped in a type-unsafe wrapper
+(ClientSocketPoolBase::ConnectJobFactoryAdaptor) so that it can be
+passed to the initialization of the ClientSocketPoolBaseHelper.  This
+allows the helper to create connect jobs while preserving a type-safe
+API to the initialization of the socket pool.
+
 ### SSL
 
 When an SSL connection is needed, the ClientSocketPoolManager assembles the
 parameters needed both to connect the TCP socket and establish an SSL
 connection. It then passes them to the SSLClientSocketPool, which creates
 an SSLConnectJob using them. The SSLConnectJob's first step is to call into the
 TransportSocketPool to establish a TCP connection.
 
 Once a connection is established by the lower layered pool, the SSLConnectJob
 then starts SSL negotiation. Once that's done, the SSL socket is passed back to
@@ skipping 71 matching lines @@
 connection is established, the first usable connection goes to the highest
 priority socket request.
 
 ## Non-HTTP Schemes
 
 The URLRequestJobFactory has a ProtocolHander for each supported scheme.
 Non-HTTP URLRequests have their own ProtocolHandlers. Some are implemented in
 net/, (like FTP, file, and data, though the renderer handles some data URLs
 internally), and others are implemented in content/ or chrome (like blob,
 chrome, and chrome-extension).