1 /* 2 * Copyright (C) 2016, Google Inc. and others 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the Eclipse Distribution License v. 1.0 which is available at 6 * https://www.eclipse.org/org/documents/edl-v10.php. 7 * 8 * SPDX-License-Identifier: BSD-3-Clause 9 */ 10 11 package org.eclipse.jgit.internal.ketch; 12 13 import java.io.IOException; 14 import java.util.List; 15 16 import org.eclipse.jgit.lib.AnyObjectId; 17 import org.eclipse.jgit.transport.ReceiveCommand; 18 19 /** 20 * One round-trip to all replicas proposing a log entry. 21 * <p> 22 * In Raft a log entry represents a state transition at a specific index in the 23 * replicated log. The leader can only append log entries to the log. 24 * <p> 25 * In Ketch a log entry is recorded under the {@code refs/txn} namespace. This 26 * occurs when: 27 * <ul> 28 * <li>a replica wants to establish itself as a new leader by proposing a new 29 * term (see {@link ElectionRound}) 30 * <li>an established leader wants to gain consensus on new {@link Proposal}s 31 * (see {@link ProposalRound}) 32 * </ul> 33 */ 34 abstract class Round { 35 final KetchLeader leader; 36 final LogIndex acceptedOldIndex; 37 LogIndex acceptedNewIndex; 38 List<ReceiveCommand> stageCommands; 39 40 Round(KetchLeader leader, LogIndex head) { 41 this.leader = leader; 42 this.acceptedOldIndex = head; 43 } 44 45 KetchSystem getSystem() { 46 return leader.getSystem(); 47 } 48 49 /** 50 * Creates a commit for {@code refs/txn/accepted} and calls 51 * {@link #runAsync(AnyObjectId)} to begin execution of the round across 52 * the system. 53 * <p> 54 * If references are being updated (such as in a {@link ProposalRound}) the 55 * RefTree may be modified. 56 * <p> 57 * Invoked without {@link KetchLeader#lock} to build objects. 58 * 59 * @throws IOException 60 * the round cannot build new objects within the leader's 61 * repository. The leader may be unable to execute. 62 */ 63 abstract void start() throws IOException; 64 65 /** 66 * Asynchronously distribute the round's new value for 67 * {@code refs/txn/accepted} to all replicas. 68 * <p> 69 * Invoked by {@link #start()} after new commits have been created for the 70 * log. The method passes {@code newId} to {@link KetchLeader} to be 71 * distributed to all known replicas. 72 * 73 * @param newId 74 * new value for {@code refs/txn/accepted}. 75 */ 76 void runAsync(AnyObjectId newId) { 77 acceptedNewIndex = acceptedOldIndex.nextIndex(newId); 78 leader.runAsync(this); 79 } 80 81 /** 82 * Notify the round it was accepted by a majority of the system. 83 * <p> 84 * Invoked by the leader with {@link KetchLeader#lock} held by the caller. 85 */ 86 abstract void success(); 87 }