doc improvement

I hope that this will clarify #325, and #132.

diff --git a/src/bindings/java/org/simgrid/msg/ProcessKilledError.java b/src/bindings/java/org/simgrid/msg/ProcessKilledError.java
index 41f4454..b9ebb49 100644 (file)
--- a/src/bindings/java/org/simgrid/msg/ProcessKilledError.java
+++ b/src/bindings/java/org/simgrid/msg/ProcessKilledError.java
@@ -6,7 +6,17 @@
 package org.simgrid.msg;
 
 /** Used internally to interrupt the user code when the process gets killed.
- * Don't catch it.
+ *
+ * You can catch it for cleanups or to debug, but DO NOT BLOCK IT, or your simulation will segfault!
+ *
+ * <code>
+ * try {
+ *   getHost().off();
+ * } catch (ProcessKilledError e) {
+ *   e.printStackTrace();
+ *   throw e;
+ * }
+ * </code>
  */
 
 public class ProcessKilledError extends Error {

diff --git a/src/kernel/context/Context.hpp b/src/kernel/context/Context.hpp
index 4486bd0..7bacdcf 100644 (file)
--- a/src/kernel/context/Context.hpp
+++ b/src/kernel/context/Context.hpp
@@ -87,7 +87,24 @@ public:
 };
 
 class XBT_PUBLIC StopRequest {
-  /** @brief Exception launched to kill a process, in order to properly unwind its stack and release RAII stuff
+  /** @brief Exception launched to kill an actor; do not block it!
+   *
+   * This exception is thrown whenever the actor's host is turned off. The actor stack is properly unwinded to release
+   * all objects allocated on the stack (RAII powa).
+   *
+   * You may want to catch this exception to perform some extra cleanups in your simulation, but YOUR ACTORS MUST NEVER
+   * SURVIVE a StopRequest, or your simulation will segfault.
+   *
+   * @verbatim
+   * void* payload = malloc(512);
+   *
+   * try {
+   *   simgrid::s4u::this_actor::execute(100000);
+   * } catch (simgrid::kernel::context::StopRequest& e) { // oops, my host just turned off
+   *   free(malloc);
+   *   throw; // I shall never survive on an host that was switched off
+   * }
+   * @endverbatim
    *
    * Nope, Sonar, this should not inherit of std::exception nor of simgrid::Exception.
    * Otherwise, users may accidentally catch it with a try {} catch (std::exception)