From b8f3a029d3c59f037fd42eb2aed7ff926d62db8b Mon Sep 17 00:00:00 2001 From: Roberto Tyley Date: Tue, 11 Mar 2014 12:52:04 +0000 Subject: [PATCH 1/3] Document that OkHttpClient is thread-safe While investigating a race-condition, I was momentarily worried when I couldn't find any documentation actually stating that OkHttpClient is thread-safe, apart from this Google+ post: https://plus.google.com/118239425803358296962/posts/5nzAvPaitHu ...if I'm not the only person asking this question, probably best to document it. --- .../src/main/java/com/squareup/okhttp/OkHttpClient.java | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java b/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java index e2fd6104a..c978d7cc7 100644 --- a/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java +++ b/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java @@ -40,7 +40,11 @@ import javax.net.ssl.SSLContext; import javax.net.ssl.SSLSocketFactory; import okio.ByteString; -/** Configures and creates HTTP connections. */ +/** + * Configures and creates HTTP connections. Designed to be treated as a singleton - by + * using a single instance you are afforded a shared response cache, thread pool, connection + * re-use, etc. + */ public final class OkHttpClient implements URLStreamHandlerFactory, Cloneable { private final RouteDatabase routeDatabase; @@ -417,6 +421,9 @@ public final class OkHttpClient implements URLStreamHandlerFactory, Cloneable { dispatcher.cancel(tag); } + /** + * This method is thread-safe. + */ public HttpURLConnection open(URL url) { return open(url, proxy); } From 8a0b263b7a8a8ceae0bf72f8b463ee78f7963b80 Mon Sep 17 00:00:00 2001 From: Roberto Tyley Date: Tue, 11 Mar 2014 17:51:41 +0000 Subject: [PATCH 2/3] Doc: OkHttpClient need not /always/ be a singleton --- okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java b/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java index c978d7cc7..9d3577b2a 100644 --- a/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java +++ b/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java @@ -41,9 +41,9 @@ import javax.net.ssl.SSLSocketFactory; import okio.ByteString; /** - * Configures and creates HTTP connections. Designed to be treated as a singleton - by - * using a single instance you are afforded a shared response cache, thread pool, connection - * re-use, etc. + * Configures and creates HTTP connections. Most applications can use a single + * OkHttpClient for all of their HTTP requests - benefiting from a shared + * response cache, thread pool, connection re-use, etc. */ public final class OkHttpClient implements URLStreamHandlerFactory, Cloneable { From 6b17f9edf338173c6491cc30feeb6e4ff539be9d Mon Sep 17 00:00:00 2001 From: Roberto Tyley Date: Tue, 11 Mar 2014 19:57:33 +0000 Subject: [PATCH 3/3] Doc: OkHttpClient should be treated as immutable once shared ...given that requirement, it's safe for many threads to call the open() method concurrently to open their own connections. https://github.com/square/okhttp/pull/634#discussion_r10487815 --- .../src/main/java/com/squareup/okhttp/OkHttpClient.java | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java b/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java index 9d3577b2a..bb4be687a 100644 --- a/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java +++ b/okhttp/src/main/java/com/squareup/okhttp/OkHttpClient.java @@ -44,6 +44,12 @@ import okio.ByteString; * Configures and creates HTTP connections. Most applications can use a single * OkHttpClient for all of their HTTP requests - benefiting from a shared * response cache, thread pool, connection re-use, etc. + * + * Instances of OkHttpClient are intended to be fully configured before they're + * shared - once shared they should be treated as immutable and can safely be used + * to concurrently open new connections. If required, threads can call + * {@link #clone()} to make a shallow copy of the OkHttpClient that can be + * safely modified with further configuration changes. */ public final class OkHttpClient implements URLStreamHandlerFactory, Cloneable { @@ -421,9 +427,6 @@ public final class OkHttpClient implements URLStreamHandlerFactory, Cloneable { dispatcher.cancel(tag); } - /** - * This method is thread-safe. - */ public HttpURLConnection open(URL url) { return open(url, proxy); }