From 0b386fbeb72e5770c5d74334f20cb64e84d73a78 Mon Sep 17 00:00:00 2001
From: Luc Maisonobe <luc@orekit.org>
Date: Sat, 12 Jan 2019 09:28:06 +0100
Subject: [PATCH] Improved javadoc.

The previous explanation for multi-threading and propagation set up for
fixing #479 was incomplete. The fact is that propagators cannot be
called from several threads at once (they do preserve some internal
state), but they CAN be used in multi-threaded applications as long as
one propagator is only called from one thread. We even have a helper
class for that: PropagatorsParallelizer.

Fixes #479
---
 .../java/org/orekit/propagation/Propagator.java  | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/main/java/org/orekit/propagation/Propagator.java b/src/main/java/org/orekit/propagation/Propagator.java
index 678b1fd66..1b83b05c3 100644
--- a/src/main/java/org/orekit/propagation/Propagator.java
+++ b/src/main/java/org/orekit/propagation/Propagator.java
@@ -37,11 +37,17 @@ import org.orekit.utils.PVCoordinatesProvider;
  * using rich force models and by continuous models built after numerical
  * integration has been completed and dense output data as been
  * gathered.</p>
- * <p>Note that propagators are <em>not</em> thread-safe. There configuration
- * can be changed as there is at least a {@link #resetInitialState(SpacecraftState)}
- * method, and even propagators that do not support resetting state (like the
- * {@link org.orekit.propagation.analytical.tle.TLEPropagator TLEPropagator} do
- * cache some internal data during computation.</p>
+ * <p>Note that one single propagator cannot be called from multiple threads.
+ * Its configuration can be changed as there is at least a {@link
+ * #resetInitialState(SpacecraftState)} method, and even propagators that do
+ * not support resetting state (like the {@link
+ * org.orekit.propagation.analytical.tle.TLEPropagator TLEPropagator} do
+ * cache some internal data during computation. However, as long as they
+ * are configured with independent building blocks (mainly event handlers
+ * and step handlers that may preserve some internal state), and as long
+ * as they are called from one thread only, they <em>can</em> be used in
+ * multi-threaded applications. Synchronizing several propagators to run in
+ * parallel is also possible using {@link PropagatorsParallelizer}.</p>
  * @author Luc Maisonobe
  * @author V&eacute;ronique Pommier-Maurussane
  *
-- 
GitLab