Copilot commented on code in PR #19117:
URL: https://github.com/apache/pinot/pull/19117#discussion_r3676858641
##########
pinot-common/src/main/java/org/apache/pinot/common/utils/DataSchema.java:
##########
@@ -57,14 +56,23 @@
import static java.nio.charset.StandardCharsets.UTF_8;
-/**
- * The <code>DataSchema</code> class describes the schema of {@link DataTable}.
- */
+/// Describes the schema of a [org.apache.pinot.common.datatable.DataTable].
+///
+/// Instances are effectively immutable and safe to share across threads.
Sharing is common: in the multi-stage engine
+/// a stage plan is deserialized once per stage and then handed to every
worker of that stage, so the `DataSchema` of
+/// each plan node is read concurrently by all worker threads on the server.
Review Comment:
The new `///` comments are only treated as documentation comments by the JDK
tooling if the project is building with a Java version that supports Markdown
documentation comments (and has it enabled, if applicable). If Pinot is still
built with a pre-Markdown-doc-comments JDK (commonly 11/17), these lines become
plain `//` comments and won’t satisfy Javadoc/Checkstyle requirements or appear
in generated API docs. Consider keeping these as standard Javadoc (`/** ...
*/`) or confirm/update the build/tooling and style checks to explicitly support
`///` Markdown doc comments.
##########
pinot-common/src/main/java/org/apache/pinot/common/utils/DataSchema.java:
##########
@@ -101,9 +109,11 @@ public ColumnDataType[] getColumnDataTypes() {
return _columnDataTypes;
}
- /**
- * Lazy compute the _storeColumnDataTypes field.
- */
+ /// Returns the stored type of each column, lazily computing and caching it
on first access.
+ ///
+ /// Uses the racy-single-check idiom: two threads may each compute the
array, but both compute the same values, so
+ /// the duplicate work is harmless. Correctness relies on
`_storedColumnDataTypes` being `volatile`; see the field
+ /// for why.
Review Comment:
The inline link syntax `[#getStoredColumnDataTypes]` and
`[org.apache.pinot.common.datatable.DataTable]` is not standard for Java doc
tooling; even with Markdown doc comments, Javadoc typically expects `{@link
...}` (and for members, `{@link #getStoredColumnDataTypes()}`) to produce
resolvable API links. Updating these references to Javadoc link tags (or the
exact Markdown-link format supported by your JDK’s javadoc implementation) will
prevent dead/unresolved references in generated docs.
##########
pinot-common/src/main/java/org/apache/pinot/common/utils/DataSchema.java:
##########
@@ -57,14 +56,23 @@
import static java.nio.charset.StandardCharsets.UTF_8;
-/**
- * The <code>DataSchema</code> class describes the schema of {@link DataTable}.
- */
+/// Describes the schema of a [org.apache.pinot.common.datatable.DataTable].
+///
+/// Instances are effectively immutable and safe to share across threads.
Sharing is common: in the multi-stage engine
+/// a stage plan is deserialized once per stage and then handed to every
worker of that stage, so the `DataSchema` of
+/// each plan node is read concurrently by all worker threads on the server.
@JsonPropertyOrder({"columnNames", "columnDataTypes"})
public class DataSchema {
private final String[] _columnNames;
private final ColumnDataType[] _columnDataTypes;
- private ColumnDataType[] _storedColumnDataTypes;
+
+ /// Lazily computed cache of [#getStoredColumnDataTypes].
+ ///
+ /// `volatile` is required, not just for the null check in
[#getStoredColumnDataTypes]: without it the array
+ /// contents are published unsafely, and a racing thread can read the
non-null array reference while still seeing
+ /// `null` for its elements. Downstream code (e.g. `TypeUtils.convert`,
`DataBlockExtractUtils.extractValue`) then
+ /// switches on a `null` stored type and fails with a `NullPointerException`.
Review Comment:
The inline link syntax `[#getStoredColumnDataTypes]` and
`[org.apache.pinot.common.datatable.DataTable]` is not standard for Java doc
tooling; even with Markdown doc comments, Javadoc typically expects `{@link
...}` (and for members, `{@link #getStoredColumnDataTypes()}`) to produce
resolvable API links. Updating these references to Javadoc link tags (or the
exact Markdown-link format supported by your JDK’s javadoc implementation) will
prevent dead/unresolved references in generated docs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
