Merge pull request #5981 from vespa-engine/freva/add-suspendConverge

Add suspendConverge() to IdempotentTask

1 files changed, 33 insertions, 13 deletions

diff --git a/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java b/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java
index d2c09aae22a..71e55c36284 100644
--- a/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java
+++ b/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java
@@ -2,31 +2,33 @@
 package com.yahoo.vespa.hosted.node.admin.component;
 
 /**
- * This class is thread unsafe: All method calls MUST be exclusive and serialized.
+ * <p>This class is thread unsafe: All method calls MUST be exclusive and serialized.</p>
  *
- * In a specialized environment it is possible to provide a richer context than TaskContext:
- *  - Define a subclass T of TaskContext with the additional functionality.
- *  - Define task classes that implement IdempotentTask&lt;T&gt;.
+ * <dl>
+ *   <dt>In a specialized environment it is possible to provide a richer context than TaskContext:</dt>
+ *   <dd>- Define a subclass T of TaskContext with the additional functionality.</dd>
+ *   <dd>- Define task classes that implement IdempotentTask&lt;T&gt;.</dd>
+ * </dl>
  */
 public interface IdempotentTask<T extends TaskContext> {
     /**
-     *  A short id of the task to e.g. identify the task in the log.
+     *  <p>A short id of the task to e.g. identify the task in the log.</p>
      *
-     *  Prefer PascalCase and without white-space.
+     *  <p>Prefer PascalCase and without white-space.</p>
      *
-     *  Example: "EnableDocker"
+     *  <p>Example: "EnableDocker"</p>
      */
     default String name() { return getClass().getSimpleName(); }
 
     /**
-     * Execute an administrative task to converge towards some ideal state, whether it is
-     * system state or in-memory Java state.
+     * <p>Execute an administrative task to converge towards some ideal state, whether it is
+     * system state or in-memory Java state.</p>
      *
-     * converge() must be idempotent: it may be called any number of times, or
-     * interrupted at any time e.g. by `kill -9`.
+     * <p>converge() must be idempotent: it may be called any number of times, or
+     * interrupted at any time e.g. by `kill -9`.</p>
      *
-     * converge() is not thread safe: The caller must ensure there is at most one invocation
-     * of converge() at any given time.
+     * <p>converge() is not thread safe: The caller must ensure there is at most one invocation
+     * of converge() at any given time.</p>
      *
      * @return false if already converged, i.e. was a no-op. A typical sequence of converge()
      *         calls on a IdempotentTask will consist of:
@@ -38,4 +40,22 @@ public interface IdempotentTask<T extends TaskContext> {
      * @throws RuntimeException (or a subclass) if the task is unable to converge.
      */
     boolean converge(T context);
+
+    /**
+     * <p>Converge the task towards some state where it can be suspended. The
+     * TaskContext should provide enough to determine what kind of suspend is wanted, e.g.
+     * suspension of only the task, or the task and the resources/processes it manages.</p>
+     *
+     * <p>convergeSuspend() must be idempotent: it may be called any number of times, or
+     * interrupted at any time e.g. by `kill -9`.</p>
+     *
+     * <p>convergeSuspend() is not thread safe: The caller must ensure there is at most one
+     * invocation of convergeSuspend() at any given time.</p>
+     *
+     * @return false if already converged, i.e. was a no-op
+     * @throws RuntimeException (or a subclass) if the task is unable to suspend.
+     */
+    default boolean convergeSuspend(T context) {
+        return false;
+    }
 }