From 88f49834fd2196de9543a02d0e4dbce327353045 Mon Sep 17 00:00:00 2001 From: Viktor Lofgren Date: Fri, 27 Oct 2023 12:45:39 +0200 Subject: [PATCH] (docs) Update documentation --- code/libraries/message-queue/readme.md | 64 +++++++------------ code/readme.md | 1 + code/services-core/executor-service/readme.md | 12 ++++ code/services-core/index-service/readme.md | 2 +- 4 files changed, 38 insertions(+), 41 deletions(-) create mode 100644 code/services-core/executor-service/readme.md diff --git a/code/libraries/message-queue/readme.md b/code/libraries/message-queue/readme.md index cc7fbb60..1f45e12f 100644 --- a/code/libraries/message-queue/readme.md +++ b/code/libraries/message-queue/readme.md @@ -26,57 +26,40 @@ The inbox implementations as well as the outbox can be constructed via the `Mess The MQSM is a finite state machine that is backed by the message queue used to implement an Actor style paradigm. -The machine itself is defined through a class that extends the 'AbstractActorPrototype'; with state transitions and +The machine itself is defined through a class that extends the 'RecordActorPrototype'; with state transitions and names defined as implementations. Example: ```java -class ExampleStateMachine extends AbstractActorPrototype { - - @ActorState(name = "INITIAL", next="GREET") - public void initial() { - return "World"; // passed to the next state - } +class ExampleStateMachine extends RecordActorPrototype { - @ActorState(name = "GREET", next="COUNT-TO-FIVE") - public void greet(String name) { - System.out.println("Hello " + name); - } + public record Initial() implements ActorStep {} + public record Greet(String message) implements ActorStep {} + public record CountDown(int from) implements ActorStep {} - @ActorState(name = "COUNT-TO-FIVE", next="END") - public void countToFive(Integer value) { - // value is passed from the previous state, since greet didn't pass a value, - // null will be the default. - - if (null == value) { - // jumps to the current state with a value of 0 - transition("COUNT-TO-FIVE", 0); - } - - - System.out.println(++value); - if (value < 5) { - // Loops the current state until value = 5 - transition("COUNT-TO-FIVE", value); - } - - if (value > 5) { - // demonstrates an error condition - error("Illegal value"); - } - - // Default transition is to END - } - - @ActorState(name="END") - public void end() { - System.out.println("Done"); + @Override + public ActorStep transition(ActorStep self) { + return switch (self) { + case Initial i -> new Greet("World"); + case Greet(String name) -> { + System.out.println("Hello " + name + "!"); + yield new CountDown(5); + } + case CountDown (int from) -> { + if (from > 0) { + System.out.println(from); + yield new CountDown(from - 1); + } + yield new End(); + } + default -> new Error(); + }; } } ``` -Each method should ideally be idempotent, or at least be able to handle being called multiple times. +Each step should ideally be idempotent, or at least be able to handle being called multiple times. It can not be assumed that the states are invoked within the same process, or even on the same machine, on the same day, etc. @@ -90,6 +73,7 @@ To create an ActorStateMachine from the above class, the following code can be u ActorStateMachine actorStateMachine = new ActorStateMachine( messageQueueFactory, actorInboxName, + node, actorInstanceUUID, new ExampleStateMachine()); diff --git a/code/readme.md b/code/readme.md index dd6403a1..c10d1c8e 100644 --- a/code/readme.md +++ b/code/readme.md @@ -17,6 +17,7 @@ A map of the most important components and how they relate can be found below. * * [control](services-core/control-service) * * [query](services-core/query-service) * * [index](services-core/index-service) +* * [executor](services-core/executor-service) * * [assistant](services-core/assistant-service) * [application services](services-application/) "microservices", stateless providing additional functionality and making an application out of the search engine. * * [api](services-application/api-service) - public API diff --git a/code/services-core/executor-service/readme.md b/code/services-core/executor-service/readme.md new file mode 100644 index 00000000..37fad036 --- /dev/null +++ b/code/services-core/executor-service/readme.md @@ -0,0 +1,12 @@ +The executor service is a partitioned service responsible for executing and keeping +track of long running maintenance and operational tasks, such as crawling or data +processing. + +It accomplishes this using the [message queue and actor library](../../libraries/message-queue/), +which permits program state to survive crashes and reboots. The executor service is closely +linked to the [control-service](../control-service), which provides a user interface for +much of the executor's functionality. + +## Central Classes + +* [ExecutorActorControlService](src/main/java/nu/marginalia/actor/ExecutorActorControlService.java) \ No newline at end of file diff --git a/code/services-core/index-service/readme.md b/code/services-core/index-service/readme.md index e7e0977a..97c17cc6 100644 --- a/code/services-core/index-service/readme.md +++ b/code/services-core/index-service/readme.md @@ -1,6 +1,6 @@ # Index Service -The index service knows which document contains which keywords. +The index service is a partitioned service that knows which document contains which keywords. ![image](../../../doc/diagram/index-service-map.svg)