executor
Last updated: 2024-09-27 10:47:22.374848 File source: link on GitLab
executor
Table of Contents
Specification
Description
The executor package is responsible for executing the jobs received by the device management service (DMS). It provides an unified interface to run various executors such as docker, firecracker etc
Structure and Organisation
Here is quick overview of the contents of this pacakge:
README: Current file which is aimed towards developers who wish to use and modify the executor functionality.
init: This file initializes a logger instance for the executor package.
types: This file contains the interfaces that other packages in the DMS call to utilise functionality offered by the executor package.
docker: This folder contains the implementation of docker executor.
firecracker: This folder contains the implementation of firecracker executor.
Class Diagram
Source
Rendered from source file
Functionality
The main functionality offered by the executor
package is defined via the Executor
interface.
Its methods are explained below:
Start
signature:
Start(ctx context.Context, request executor.ExecutionRequest) -> error
input #1:
Go context
input #2:
executor.ExecutionRequest
output:
error
Start
function takes a Go context
object and a executor.ExecutionRequest
type as input. It returns an error if the execution already exists and is in a started or terminal state. Implementations may also return other errors based on resource limitations or internal faults.
Run
signature:
Run(ctx context.Context, request executor.ExecutionRequest) -> (executor.ExecutionResult, error)
input #1:
Go context
input #2:
executor.ExecutionRequest
output (success):
executor.ExecutionResult
output (error):
error
Run
initiates and waits for the completion of an execution for the given Execution Request. It returns a executor.ExecutionResult
and an error if any part of the operation fails. Specifically, it will return an error if the execution already exists and is in a started or terminal state.
Wait
signature:
Wait(ctx context.Context, executionID string) -> (<-chan executor.ExecutionResult, <-chan error)
input #1:
Go context
input #2:
executor.ExecutionRequest.ExecutionID
output #1: Channel that returns
executor.ExecutionResult
output #2: Channel that returns
error
Wait
monitors the completion of an execution identified by its executionID
. It returns two channels:
A channel that emits the execution result once the task is complete;
An error channel that relays any issues encountered, such as when the execution is non-existent or has already concluded.
Cancel
signature:
Cancel(ctx context.Context, executionID string) -> error
input #1:
Go context
input #2:
executor.ExecutionRequest.ExecutionID
output:
error
Cancel
attempts to terminate an ongoing execution identified by its executionID
. It returns an error if the execution does not exist or is already in a terminal state.
GetLogStream
signature:
GetLogStream(ctx context.Context, request executor.LogStreamRequest, executionID string) -> (io.ReadCloser, error)
input #1:
Go context
input #2:
executor.LogStreamRequest
input #3:
executor.ExecutionRequest.ExecutionID
output #1:
io.ReadCloser
output #2:
error
GetLogStream
provides a stream of output for an ongoing or completed execution identified by its executionID
. There are two flags that can be used to modify the functionality:
The
Tail
flag indicates whether to exclude historical data or not.The
follow
flag indicates whether the stream should continue to send data as it is produced.
It returns an io.ReadCloser
object to read the output stream and an error if the operation fails. Specifically, it will return an error if the execution does not exist.
Data Types
types.ExecutionRequest
: This is the input thatexecutor
receives to initiate a job execution.types.ExecutionResult
: This contains the result of the job execution.executor.LogStreamRequest
: This contains input parameters sent to theexecutor
to get job execution logs.
types.SpecConfig
: This allows arbitrary configuration/parameters as needed during implementation of specific executor.types.Resources
: This contains resources to be used for execution.storage.StorageVolume
: This contains parameters of storage volume used during execution.
Testing
Unit tests are defined in subpackages which implement the interface defined in this package.
Proposed Functionality / Requirements
List of issues
All issues that are related to the implementation of executor
package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.
References
Last updated