mirror of
https://github.com/enso-org/enso.git
synced 2024-12-27 22:18:43 +03:00
110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
---
|
|
layout: developer-doc
|
|
title: Execution Server Flow
|
|
category: runtime
|
|
tags: [runtime, execution, language-server]
|
|
order: 6
|
|
---
|
|
|
|
# Execution Server Flow
|
|
|
|
This document describes the API and workflow of the internal execution server.
|
|
|
|
<!-- MarkdownTOC levels="2,3" autolink="true" -->
|
|
|
|
- [Opening a Connection](#opening-a-connection)
|
|
- [API](#api)
|
|
- [Internal Architecture](#internal-architecture)
|
|
- [Job Queue](#job-queue)
|
|
- [Job Types](#job-types)
|
|
- [Scheduling Rules](#scheduling-rules)
|
|
- [API Methods to Jobs Translation](#api-methods-to-jobs-translation)
|
|
|
|
<!-- /MarkdownTOC -->
|
|
|
|
## Opening a Connection
|
|
|
|
> The actionables for this section are:
|
|
>
|
|
> 1. describe the `org.graalvm.polyglot.Context.Builder.serverTransport`
|
|
> workflow of connecting to the server.
|
|
|
|
## API
|
|
|
|
> The actionables for this section are:
|
|
>
|
|
> 1. Document the server's API.
|
|
|
|
## Internal Architecture
|
|
|
|
This section describes certain implementation details of the execution server,
|
|
allowing it to perform its operations safely and interactively.
|
|
|
|
### Job Queue
|
|
|
|
The execution server uses a job queue containing requests to be performed. An
|
|
API method may queue multiple jobs.
|
|
|
|
### Job Types
|
|
|
|
There are a number of job types used internally for handling different
|
|
scenarios:
|
|
|
|
#### `EnsureCompiled`
|
|
|
|
Takes a set of module names that must be compiled and ensures that the
|
|
corresponding modules are compiled in the newest version. It also performs cache
|
|
invalidations on changes since the last batch. Caches should be invalidated for
|
|
all contexts affected by this recompilation. This operation is idempotent and
|
|
should be run before any `Execute` action. This operation is not currently
|
|
interruptible, but may become so in the future.
|
|
|
|
#### `Execute`
|
|
|
|
Takes a context ID and an optional set of expression IDs that should be
|
|
executed. and executes the Enso code corresponding to the context's stack.
|
|
Updates caches and sends updates to the users.
|
|
|
|
This operation is interruptible through `Thread.interrupt()`.
|
|
|
|
### Scheduling Rules
|
|
|
|
1. `EnsureCompiled` jobs must be run sequentially (i.e. no other state
|
|
modifications or executions are allowed during this job's run).
|
|
2. `Execute` jobs may be run in parallel with each other (but not with
|
|
`EnsureCompiled` jobs).
|
|
3. `EnsureCompiled` jobs may be collapsed into one, by unifying their module
|
|
sets.
|
|
4. `Execute` jobs with the same `contextId` may be collapsed into one, by
|
|
merging their `expression IDs` sets.
|
|
5. All enqueued `EnsureCompiled` jobs should run before any `Execute` jobs.
|
|
6. The order of `EnsureCompiled` jobs can be freely changed by the compiler.
|
|
|
|
### API Methods to Jobs Translation
|
|
|
|
The following describes handling of API messages through job queue
|
|
modifications.
|
|
|
|
1. EditFile:
|
|
1. Abort and/or dequeue all pending and running messages (if possible).
|
|
2. Synchronously perform all code updates.
|
|
3. Enqueue an `EnsureCompiled` with all affected files.
|
|
4. Enqueue an `Execute` for each existing context.
|
|
2. Stack Modifications and Recomputes:
|
|
1. Abort and/or dequeue all pending and running requests relevant to the
|
|
affected context.
|
|
2. Synchronously perform all state updates.
|
|
3. Respond to the user.
|
|
4. Enqueue EnsureCompiled for the file at the bottom of the affected
|
|
context's stack.
|
|
5. Enqueue Execute for the affected context.
|
|
3. Visualization modifications:
|
|
1. Synchronously perform all state updates.
|
|
2. Respond to the user.
|
|
3. Enqueue `EnsureCompiled` and `Execute` for the affected context. Set the
|
|
minimal set of expressions required to compute to
|
|
`Set(visualizedExpression)` in the `Execute` command.
|
|
4. Create/Destroy context:
|
|
1. Abort any jobs concerning the affected context.
|
|
2. Perform state updates / cleanups. No jobs to schedule.
|