okhttp3.internal.connection

Class StreamAllocation

java.lang.Object

okhttp3.internal.connection.StreamAllocation

public final class StreamAllocation
extends Object

This class coordinates the relationship between three entities:

• Connections: physical socket connections to remote servers. These are potentially slow to establish so it is necessary to be able to cancel a connection currently being connected.
• Streams: logical HTTP request/response pairs that are layered on connections. Each connection has its own allocation limit, which defines how many concurrent streams that connection can carry. HTTP/1.x connections can carry 1 stream at a time, HTTP/2 typically carry multiple.
• Calls: a logical sequence of streams, typically an initial request and its follow up requests. We prefer to keep all streams of a single call on the same connection for better behavior and locality.

Instances of this class act on behalf of the call, using one or more streams over one or more connections. This class has APIs to release each of the above resources:

• noNewStreams() prevents the connection from being used for new streams in the future. Use this after a Connection: close header, or when the connection may be inconsistent.
• streamFinished() releases the active stream from this allocation. Note that only one stream may be active at a given time, so it is necessary to call streamFinished() before creating a subsequent stream with newStream().
• release() removes the call's hold on the connection. Note that this won't immediately free the connection if there is a stream still lingering. That happens when a call is complete but its response body has yet to be fully consumed.

This class supports asynchronous canceling. This is intended to have the smallest blast radius possible. If an HTTP/2 stream is active, canceling will cancel that stream but not the other streams sharing its connection. But if the TLS handshake is still in progress then canceling may break the entire connection.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	StreamAllocation.StreamAllocationReference

Field Summary

Fields

Modifier and Type	Field and Description
Address	address

Constructor Summary

Constructors

Constructor and Description
StreamAllocation(ConnectionPool connectionPool, Address address, Object callStackTrace)

Method Summary

Modifier and Type	Method and Description
void	acquire(RealConnection connection) Use this allocation to hold connection.
void	cancel()
HttpCodec	codec()
RealConnection	connection()
boolean	hasMoreRoutes()
HttpCodec	newStream(OkHttpClient client, boolean doExtensiveHealthChecks)
void	noNewStreams() Forbid new streams from being created on the connection that hosts this allocation.
void	release()
Socket	releaseAndAcquire(RealConnection newConnection) Release the connection held by this connection and acquire newConnection instead.
void	streamFailed(IOException e)
void	streamFinished(boolean noNewStreams, HttpCodec codec)
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

address

public final Address address

Constructor Detail

StreamAllocation

public StreamAllocation(ConnectionPool connectionPool,
                        Address address,
                        Object callStackTrace)

Method Detail

newStream

public HttpCodec newStream(OkHttpClient client,
                           boolean doExtensiveHealthChecks)

streamFinished

public void streamFinished(boolean noNewStreams,
                           HttpCodec codec)

codec

public HttpCodec codec()

connection

public RealConnection connection()

release

public void release()

noNewStreams

public void noNewStreams()

Forbid new streams from being created on the connection that hosts this allocation.

cancel

public void cancel()

streamFailed

public void streamFailed(IOException e)

acquire

public void acquire(RealConnection connection)

Use this allocation to hold connection. Each call to this must be paired with a call to release() on the same connection.

releaseAndAcquire

public Socket releaseAndAcquire(RealConnection newConnection)

Release the connection held by this connection and acquire newConnection instead. It is only safe to call this if the held connection is newly connected but duplicated by newConnection. Typically this occurs when concurrently connecting to an HTTP/2 webserver.

Returns a closeable that the caller should pass to Util.closeQuietly(java.io.Closeable) upon completion of the synchronized block. (We don't do I/O while synchronized on the connection pool.)

hasMoreRoutes

public boolean hasMoreRoutes()

toString

public String toString()

Overrides:

toString in class Object