io.atomix.copycat.server.StateMachineExecutor Maven / Gradle / Ivy
/*
* Copyright 2015 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.atomix.copycat.server;
import io.atomix.catalyst.util.concurrent.ThreadContext;
import io.atomix.copycat.client.Command;
import io.atomix.copycat.client.Operation;
import io.atomix.copycat.client.Query;
import io.atomix.copycat.server.session.Sessions;
import java.util.function.Consumer;
import java.util.function.Function;
/**
* Facilitates registration and execution of state machine commands and provides deterministic scheduling.
*
* The state machine executor is responsible for managing input to and output from a {@link StateMachine}.
* When a state machine is started within a {@link CopycatServer}, the state machine is
* {@link StateMachine#configure(StateMachineExecutor) configured} with a state machine executor. The state machine
* must register {@link Command} and {@link Query}
* (operations) callbacks via the executor.
*
* {@code
* public class MapStateMachine extends StateMachine {
* private final Map> map = new HashMap<>();
*
* protected void configure(StateMachineExecutor executor) {
* executor.register(PutCommand.class, this::put);
* }
*
* private Object put(Commit commit) {
* return map.put(commit.operation().key(), commit);
* }
* }
* }
*
* As operations are committed to the Raft log, the executor is responsible for applying them to the state machine.
* {@link Command commands} are guaranteed to be applied to the state machine in the order in which
* they appear in the Raft log and always in the same thread, so state machines don't have to be thread safe.
* {@link Query queries} are not generally written to the Raft log and will instead be applied
* according to their {@link Query.ConsistencyLevel}.
*
* State machines can use the executor to provide deterministic scheduling during command operations.
*
* {@code
* private Object putWithTtl(Commit commit) {
* map.put(commit.operation().key(), commit);
* executor().schedule(Duration.ofMillis(commit.operation().ttl()), () -> {
* map.remove(commit.operation().key());
* commit.clean();
* });
* }
* }
*
* As with all state machine callbacks, the executor will ensure scheduled callbacks are executed sequentially and
* deterministically. As long as state machines schedule callbacks deterministically, callbacks will be executed
* deterministically. Internally, the state machine executor triggers callbacks based on various timestamps in the
* Raft log. This means the scheduler is dependent on internal or user-defined operations being written to the log.
* Prior to the execution of a command, any expired scheduled callbacks will be executed based on the command's
* logged timestamp.
*
* It's important to note that callbacks can only be scheduled during {@link Command}
* operations or by recursive scheduling. If a state machine attempts to schedule a callback via the executor
* during the execution of a {@link Query}, a {@link IllegalStateException} will be
* thrown. This is because queries are usually only applied on a single state machine within the cluster, and
* so scheduling callbacks in reaction to query execution would not be deterministic.
*
* @see StateMachine
* @see StateMachineContext
*
* @author © 2015 - 2025 Weber Informatics LLC | Privacy Policy