This is an automated email from the ASF dual-hosted git repository.
jlewandowski pushed a commit to branch cep-21-tcm-review
in repository https://gitbox.apache.org/repos/asf/cassandra.git
The following commit(s) were added to refs/heads/cep-21-tcm-review by this push:
new 341dd2c95c Add JavaDoc - jacek - wip
341dd2c95c is described below
commit 341dd2c95c59aad831ed668ce4377a93958a3ead
Author: Jacek Lewandowski <[email protected]>
AuthorDate: Tue Oct 17 18:41:45 2023 +0200
Add JavaDoc - jacek - wip
---
src/java/org/apache/cassandra/db/SystemKeyspace.java | 2 ++
.../org/apache/cassandra/tcm/ClusterMetadata.java | 19 +++++++++++++++++++
.../apache/cassandra/tcm/ClusterMetadataService.java | 11 +++++++++++
.../org/apache/cassandra/tcm/InProgressSequence.java | 4 ++++
.../org/apache/cassandra/tcm/RemoteProcessor.java | 3 +++
src/java/org/apache/cassandra/tcm/log/LocalLog.java | 1 +
.../cassandra/tcm/sequences/InProgressSequences.java | 3 +++
.../cassandra/tcm/sequences/ProgressBarrier.java | 4 ++--
8 files changed, 45 insertions(+), 2 deletions(-)
diff --git a/src/java/org/apache/cassandra/db/SystemKeyspace.java
b/src/java/org/apache/cassandra/db/SystemKeyspace.java
index 51074de248..402c17219f 100644
--- a/src/java/org/apache/cassandra/db/SystemKeyspace.java
+++ b/src/java/org/apache/cassandra/db/SystemKeyspace.java
@@ -164,6 +164,8 @@ public final class SystemKeyspace
public static final String PREPARED_STATEMENTS = "prepared_statements";
public static final String REPAIRS = "repairs";
public static final String TOP_PARTITIONS = "top_partitions";
+
+ // --- TCM tables ---
public static final String METADATA_LOG = "local_metadata_log";
public static final String SNAPSHOT_TABLE_NAME = "metadata_snapshots";
public static final String SEALED_PERIODS_TABLE_NAME =
"metadata_sealed_periods";
diff --git a/src/java/org/apache/cassandra/tcm/ClusterMetadata.java
b/src/java/org/apache/cassandra/tcm/ClusterMetadata.java
index f9b08fccd7..022910d0fb 100644
--- a/src/java/org/apache/cassandra/tcm/ClusterMetadata.java
+++ b/src/java/org/apache/cassandra/tcm/ClusterMetadata.java
@@ -37,6 +37,7 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.apache.cassandra.config.CassandraRelevantProperties;
+import org.apache.cassandra.config.DatabaseDescriptor;
import org.apache.cassandra.db.TypeSizes;
import org.apache.cassandra.dht.IPartitioner;
import org.apache.cassandra.dht.Range;
@@ -54,6 +55,8 @@ import org.apache.cassandra.schema.Keyspaces;
import org.apache.cassandra.schema.ReplicationParams;
import org.apache.cassandra.tcm.extensions.ExtensionKey;
import org.apache.cassandra.tcm.extensions.ExtensionValue;
+import org.apache.cassandra.tcm.listeners.MetadataSnapshotListener;
+import org.apache.cassandra.tcm.log.LocalLog;
import org.apache.cassandra.tcm.membership.Directory;
import org.apache.cassandra.tcm.membership.Location;
import org.apache.cassandra.tcm.membership.NodeAddresses;
@@ -79,6 +82,18 @@ import org.apache.cassandra.utils.vint.VIntCoding;
import static
org.apache.cassandra.config.CassandraRelevantProperties.LINE_SEPARATOR;
import static org.apache.cassandra.db.TypeSizes.sizeof;
+/**
+ * Represents all transactional metadata of the cluster. It is versioned,
immutable and serializable.
+ * CMS guarantees that all the nodes in the cluster see the same cluster
metadata for the given epoch.
+ * When the metadata gets updated by a node, the new version must be
associated with the new epoch.
+ *
+ * Epochs are groupped into periods. The number of epoch that can fit into a
period is defined by
+ * {@link DatabaseDescriptor#getMetadataSnapshotFrequency()}. When a period is
completed, its number is incremented by
+ * {@link LocalLog#snapshotListener()}, and then, a snapshot is created by the
{@link MetadataSnapshotListener}.
+ * Both are triggered by the {@link LocalLog#processPendingInternal()} method,
which processes the log entries.
+ *
+ * @see MetadataSnapshots for more information about cluster metadata snapshots
+ */
public class ClusterMetadata
{
public static final Serializer serializer = new Serializer();
@@ -356,6 +371,10 @@ public class ClusterMetadata
return VersionedEndpoints.forToken(writeEndpoints.lastModified(),
endpointsForToken.build());
}
+ /**
+ * Builds a new cluster metadata based on top of the provided one,
registering the keys of all the overridden
+ * items.
+ */
public static class Transformer
{
private final ClusterMetadata base;
diff --git a/src/java/org/apache/cassandra/tcm/ClusterMetadataService.java
b/src/java/org/apache/cassandra/tcm/ClusterMetadataService.java
index 6871289e27..6ca65f2931 100644
--- a/src/java/org/apache/cassandra/tcm/ClusterMetadataService.java
+++ b/src/java/org/apache/cassandra/tcm/ClusterMetadataService.java
@@ -81,6 +81,17 @@ import static
org.apache.cassandra.tcm.compatibility.GossipHelper.emptyWithSchem
import static org.apache.cassandra.utils.Clock.Global.nanoTime;
import static org.apache.cassandra.utils.Collectors3.toImmutableSet;
+/**
+ * the entry point to TCM. It is responsible for transforming cluster metadata
consistently in the cluster.
+ * Transformation is performed by the current {@link Processor}.
+ *
+ * There are 3 processors availabe that are used depending on the node state:
+ * <ul>
+ * <li>gossip - the processor is used during upgrade</li>
+ * <li>local - when the node fully started and registered in CMS - that
is, it is a replica which joined the ring</li>
+ * <li>remote - when the node is not a replica / didn't join the ring</li>
+ * </ul>
+ */
public class ClusterMetadataService
{
private static final Logger logger =
LoggerFactory.getLogger(ClusterMetadataService.class);
diff --git a/src/java/org/apache/cassandra/tcm/InProgressSequence.java
b/src/java/org/apache/cassandra/tcm/InProgressSequence.java
index b7a3c01924..c0c70396cb 100644
--- a/src/java/org/apache/cassandra/tcm/InProgressSequence.java
+++ b/src/java/org/apache/cassandra/tcm/InProgressSequence.java
@@ -23,6 +23,10 @@ import
org.apache.cassandra.tcm.sequences.InProgressSequences;
import org.apache.cassandra.tcm.sequences.SequenceState;
import org.apache.cassandra.tcm.sequences.ProgressBarrier;
+/**
+ * A sequence of transformations associated with a node. When a node is
executing a sequence, the order of transformations
+ * is strictly defined. The node also cannot execute any other sequences until
the current one is completed.
+ */
public abstract class InProgressSequence<T extends InProgressSequence<T>>
{
public abstract InProgressSequences.Kind kind();
diff --git a/src/java/org/apache/cassandra/tcm/RemoteProcessor.java
b/src/java/org/apache/cassandra/tcm/RemoteProcessor.java
index c1d5c6b62b..188c88820a 100644
--- a/src/java/org/apache/cassandra/tcm/RemoteProcessor.java
+++ b/src/java/org/apache/cassandra/tcm/RemoteProcessor.java
@@ -55,6 +55,9 @@ import static
org.apache.cassandra.exceptions.ExceptionCode.SERVER_ERROR;
import static org.apache.cassandra.net.NoPayload.noPayload;
import static org.apache.cassandra.tcm.ClusterMetadataService.State.REMOTE;
+/**
+ * This processor delegates commit operation to some other node, a member of
the CMS.
+ */
public final class RemoteProcessor implements Processor
{
private static final Logger logger =
LoggerFactory.getLogger(RemoteProcessor.class);
diff --git a/src/java/org/apache/cassandra/tcm/log/LocalLog.java
b/src/java/org/apache/cassandra/tcm/log/LocalLog.java
index c1219aaa3e..8caf80df9a 100644
--- a/src/java/org/apache/cassandra/tcm/log/LocalLog.java
+++ b/src/java/org/apache/cassandra/tcm/log/LocalLog.java
@@ -659,6 +659,7 @@ public abstract class LocalLog implements Closeable
}
}
+ @VisibleForTesting // only for testing
private static class Sync extends LocalLog
{
private Sync(ClusterMetadata initial, LogStorage logStorage, boolean
addListeners, boolean isReset)
diff --git
a/src/java/org/apache/cassandra/tcm/sequences/InProgressSequences.java
b/src/java/org/apache/cassandra/tcm/sequences/InProgressSequences.java
index 412cb18b78..cf32fcf737 100644
--- a/src/java/org/apache/cassandra/tcm/sequences/InProgressSequences.java
+++ b/src/java/org/apache/cassandra/tcm/sequences/InProgressSequences.java
@@ -43,6 +43,9 @@ import org.apache.cassandra.tcm.serialization.Version;
import static org.apache.cassandra.db.TypeSizes.sizeof;
import static
org.apache.cassandra.tcm.sequences.InProgressSequences.Kind.LEAVE;
+/**
+ * A set of in-progress sequences per node. Each node can take part in only
one sequence at a time.
+ */
public class InProgressSequences implements MetadataValue<InProgressSequences>
{
public static final Serializer serializer = new Serializer();
diff --git a/src/java/org/apache/cassandra/tcm/sequences/ProgressBarrier.java
b/src/java/org/apache/cassandra/tcm/sequences/ProgressBarrier.java
index afa3db5926..7a2c64860a 100644
--- a/src/java/org/apache/cassandra/tcm/sequences/ProgressBarrier.java
+++ b/src/java/org/apache/cassandra/tcm/sequences/ProgressBarrier.java
@@ -62,7 +62,7 @@ import org.apache.cassandra.utils.concurrent.AsyncPromise;
* ProgressBarrier is responsible for ensuring that epoch visibility plays
together with quorum consistency.
*
* When bootstrapping a node, streaming will not start until (by default)
EACH_QUORUM of nodes has seen the epoch that
- * adds the joining jode to the write replica set.
+ * adds the joining node to the write replica set.
*
* Each subsequent step will be gated by waiting for (by default) EACH_QUORUM
of nodes in or proposed to be in the replica set
* to see the previous epoch.
@@ -246,7 +246,7 @@ public class ProgressBarrier
return false;
}
- public static ConsistencyLevel relaxConsistency(ConsistencyLevel cl)
+ private static ConsistencyLevel relaxConsistency(ConsistencyLevel cl)
{
logger.debug("Relaxing ProgressBarrier consistency level {}", cl);
TCMMetrics.instance.progressBarrierCLRelax.mark();
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
