JAVA-1198: Document that BoundStatement is not thread-safe. (apache#685)

olim7t · web-flow · commit 66f5814754fc · 2016-06-27T11:22:37.000-07:00
diff --git a/changelog/README.md b/changelog/README.md
@@ -12,6 +12,7 @@
 - [improvement] JAVA-1175: Warn if DCAwarePolicy configuration is inconsistent.
 - [bug] JAVA-1139: ConnectionException.getMessage() throws NPE if address is null.
 - [bug] JAVA-1202: Handle null rpc_address when checking schema agreement.
+- [improvement] JAVA-1198: Document that BoundStatement is not thread-safe.
 
 
 ### 3.0.2
diff --git a/driver-core/src/main/java/com/datastax/driver/core/BoundStatement.java b/driver-core/src/main/java/com/datastax/driver/core/BoundStatement.java
@@ -46,6 +46,11 @@
  * will be ignored server side (no tombstones will be generated). If you're reusing
  * a bound statement, you can {@link #unset(int) unset} variables that were previously
  * set.
+ * <p/>
+ * This class is <b>not thread-safe</b>. Do not share instances among requests that will
+ * execute concurrently (e.g. requests run from separate application threads, but also
+ * separate {@link Session#executeAsync(Statement) executeAsync} calls, even if they're
+ * triggered from the same thread).
  */
 public class BoundStatement extends Statement implements SettableData<BoundStatement>, GettableData {
     static final ByteBuffer UNSET = ByteBuffer.allocate(0);
diff --git a/manual/statements/prepared/README.md b/manual/statements/prepared/README.md
@@ -118,7 +118,7 @@ that were previously set:
 ```java
 BoundStatement bound = ps1.bind()
   .setString("sku", "324378")
-  .setString("description", "LCD screen")
+  .setString("description", "LCD screen");
 
 // Using the unset method to unset previously set value.
 // Positional setter:
@@ -133,8 +133,27 @@ this has a small performance overhead since values are stored in their
 serialized form.
 
 `BoundStatement` is **not thread-safe**. You can reuse an instance multiple times with different parameters, but only
-from a single thread, and only if you use the synchronous API ([Session#execute][execute] is fine,
-[Session#executeAsync][executeAsync] is not).
+from a single thread and only if you use synchronous calls:
+
+```java
+BoundStatement bound = ps1.bind();
+
+// This is safe:
+bound.setString("sku", "324378");
+session.execute(bound);
+
+bound.setString("sku", "324379");
+session.execute(bound);
+
+// This is NOT SAFE. executeAsync runs concurrently with your code, so the first execution might actually read the
+// values after the second setString call, and you would insert 324381 twice:
+bound.setString("sku", "324380");
+session.executeAsync(bound);
+
+bound.setString("sku", "324381");
+session.executeAsync(bound);
+```
+
 Also, make sure you don't accidentally reuse parameters from previous executions.
 
 ### Preparing on multiple nodes
