com.powsybl.computation.ComputationManager Maven / Gradle / Ivy
/**
* Copyright (c) 2016, All partners of the iTesla project (http://www.itesla-project.eu/consortium)
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
package com.powsybl.computation;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Path;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;
/**
*
* Computation managers have the ability to execute commands provided through an {@link ExecutionHandler}.
*
* Typically, they are used to execute expensive computations through external processes.
* According to the computation manager implementation, those processes may then be executed on the local host
* or on a dedicated computation infrastructure which may have better performance or scaling capabilities.
* Commands will be executed asynchronously and results accessible through the {@link CompletableFuture}
* returned by one of the {@link #execute} method variants. If {@link CompletableFuture#cancel} is called,
* the computation manager should try as much as possible to free computation resources used for the
* underlying commands execution.
*
*
The computation manager must provide a temporary working directory for each submitted execution,
* where data may be written to (in particular before the execution) and read from (in particular after the execution).
* A prefix for this directory may be provided through the {@link ExecutionEnvironment}.
* Typically, the prefix will be appended with a UUID to ensure working directory uniqueness.
* If {@link ExecutionEnvironment#isDebug()} is {@literal true}, that working directory will not be discarded,
* otherwise it may be discarded to ensure a sustainable use of the execution environment.
*
*
Execution handlers define a list of {@link CommandExecution}s to be executed.
* Those command executions must be executed sequentially. However, when a command execution
* has an execution number greater than one, the corresponding executions may be executed in parallel.
*
*
The interface extends {@link AutoCloseable}, since it may require some resource cleanup on closing,
* for instance deleting working directories or closing connections to remote infrastructure.
*
* @author Geoffroy Jamgotchian
*/
public interface ComputationManager extends AutoCloseable {
String getVersion();
OutputStream newCommonFile(String fileName) throws IOException;
/**
* Submits for execution commands defined by the specified {@link ExecutionHandler},
* using the specified {@link ExecutionEnvironment}.
*
* The result of type {@link R} will be provided asynchronously through the returned {@link CompletableFuture}.
*
* @param environment specifies environment details such as the working directory prefix and environment variables.
* @param handler defines the commands to be executed together with preprocessing and postprocessing.
* @param the type of the result expected from the commands execution.
* @return the result of the commands execution, as provided by the execution handler.
*/
CompletableFuture execute(ExecutionEnvironment environment, ExecutionHandler handler);
/**
* Submits for execution commands defined by the specified {@link ExecutionHandler},
* using the specified {@link ExecutionEnvironment}.
*
* The result of type {@link R} will be provided asynchronously through the returned {@link CompletableFuture}.
*
*
Additional technical parameters may be provided through the {@link ComputationParameters}.
*
* @param environment specifies environment details such as the working directory prefix and environment variables.
* @param handler defines the commands to be executed together with preprocessing and postprocessing.
* @param parameters defines additional technical parameters
* @param the type of the result expected from the commands execution.
* @return the result of the commands execution, as provided by the execution handler.
*/
default CompletableFuture execute(ExecutionEnvironment environment, ExecutionHandler handler, ComputationParameters parameters) {
return execute(environment, handler);
}
ComputationResourcesStatus getResourcesStatus();
/**
* An executor which may be used to perform expensive processing inside this JVM.
*
* @return an executor which may be used to perform expensive processing inside this JVM.
*/
Executor getExecutor();
Path getLocalDir();
@Override
void close();
}