Add notes about synchronization and performance

Author: jchambers

README.md

@@ -63,6 +63,12 @@ Current password: 164092
 Future password:  046148
 ```
 
+## Performance and best practices
+
+One-time password generators are thread-safe and reusable. Generally, applications should treat one-time password generator instances as long-lived resources.
+
+The password-generating methods in a one-time password generator are `synchronized`. In multi-threaded applications that make heavy use of a shared one-time password generator instance, synchronization may become a performance bottleneck. In that case, callers may benefit from using one instance per thread (for example, by using a [`ThreadLocal`](https://docs.oracle.com/javase/8/docs/api/java/lang/ThreadLocal.html)).
+
 ## License and copyright
 
 java-otp is published under the [MIT License](https://opensource.org/licenses/MIT).

src/main/java/com/eatthepath/otp/HmacOneTimePasswordGenerator.java

@@ -32,7 +32,11 @@
  * <p>Generates HMAC-based one-time passwords (HOTP) as specified in
  * <a href="https://tools.ietf.org/html/rfc4226">RFC&nbsp;4226</a>.</p>
  *
- * <p>{@code HmacOneTimePasswordGenerator} instances are thread-safe and may be shared between threads.</p>
+ * <p>{@code HmacOneTimePasswordGenerator} instances are thread-safe and may be shared between threads. Note that the
+ * {@link #generateOneTimePassword(Key, long)} method (and its relatives) are {@code synchronized}; in multi-threaded
+ * applications that make heavy use of a shared {@code HmacOneTimePasswordGenerator} instance, synchronization may
+ * become a performance bottleneck. In that case, callers may benefit from using one
+ * {@code HmacOneTimePasswordGenerator} instance per thread (for example, with a {@link ThreadLocal}).</p>
  *
  * @author <a href="https://github.com/jchambers">Jon Chambers</a>
  */

src/main/java/com/eatthepath/otp/TimeBasedOneTimePasswordGenerator.java

@@ -31,7 +31,11 @@
  * <p>Generates time-based one-time passwords (TOTP) as specified in
  * <a href="https://tools.ietf.org/html/rfc6238">RFC&nbsp;6238</a>.</p>
  *
- * <p>{@code TimeBasedOneTimePasswordGenerator} instances are thread-safe and may be shared between threads.</p>
+ * <p>{@code TimeBasedOneTimePasswordGenerator} instances are thread-safe and may be shared between threads. Note that
+ * the {@link #generateOneTimePassword(Key, Instant)} method (and its relatives) are {@code synchronized}; in
+ * multi-threaded applications that make heavy use of a shared {@code TimeBasedOneTimePasswordGenerator} instance,
+ * synchronization may become a performance bottleneck. In that case, callers may benefit from using one
+ * {@code TimeBasedOneTimePasswordGenerator} instance per thread (for example, with a {@link ThreadLocal}).</p>
  *
  * @author <a href="https://github.com/jchambers">Jon Chambers</a>
  */