diff options
Diffstat (limited to 'node-admin')
-rw-r--r-- | node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java | 46 |
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<T>. + * <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<T>.</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; + } } |