chore: Rename Segment to SegmentSpec (#2715)

I was reading through the writing code and I think these names are
clearer, we use `segments/segment` a bunch for different things, so this
is an attempt to make things more distinct.

Author: AdamGS

vortex-datafusion/src/persistent/cache.rs

@@ -10,7 +10,7 @@ use vortex_array::aliases::DefaultHashBuilder;
 use vortex_array::stats::{Precision, Stat};
 use vortex_dtype::DType;
 use vortex_error::{VortexError, VortexResult, vortex_err};
-use vortex_file::{Footer, Segment, VortexOpenOptions};
+use vortex_file::{Footer, SegmentSpec, VortexOpenOptions};
 use vortex_io::ObjectStoreReadAt;
 use vortex_layout::LayoutRegistry;
 use vortex_layout::segments::SegmentId;
@@ -39,7 +39,7 @@ impl From<&ObjectMeta> for Key {
 
 /// Approximate the in-memory size of a layout
 fn estimate_layout_size(footer: &Footer) -> usize {
-    let segments_size = footer.segment_map().len() * size_of::<Segment>();
+    let segments_size = footer.segment_map().len() * size_of::<SegmentSpec>();
     let stats_size = footer
         .statistics()
         .iter()

vortex-file/src/footer/mod.rs

@@ -22,7 +22,7 @@ pub struct Footer {
     ctx: ArrayContext,
     layout_ctx: LayoutContext,
     layout: Layout,
-    segments: Arc<[Segment]>,
+    segments: Arc<[SegmentSpec]>,
     statistics: Option<Arc<[StatsSet]>>,
 }
 
@@ -36,7 +36,7 @@ impl Footer {
         ctx: ArrayContext,
         layout_ctx: LayoutContext,
         root_layout: Layout,
-        segments: Arc<[Segment]>,
+        segments: Arc<[SegmentSpec]>,
         statistics: Option<Arc<[StatsSet]>>,
     ) -> Self {
         // Note this assertion is `<=` since we allow zero-length segments
@@ -108,7 +108,10 @@ impl Footer {
         let fb_segments = fb
             .segments()
             .ok_or_else(|| vortex_err!("Footer missing segments"))?;
-        let segments = fb_segments.iter().map(Segment::try_from).try_collect()?;
+        let segments = fb_segments
+            .iter()
+            .map(SegmentSpec::try_from)
+            .try_collect()?;
 
         let statistics = fb
             .statistics()
@@ -144,7 +147,7 @@ impl Footer {
     }
 
     /// Returns the segment map of the file.
-    pub fn segment_map(&self) -> &Arc<[Segment]> {
+    pub fn segment_map(&self) -> &Arc<[SegmentSpec]> {
         &self.segments
     }
 
@@ -168,7 +171,7 @@ impl Footer {
     pub(crate) fn flatbuffer_writer<'a>(
         ctx: ArrayContext,
         layout: Layout,
-        segments: Arc<[Segment]>,
+        segments: Arc<[SegmentSpec]>,
         statistics: Option<Arc<[StatsSet]>>,
     ) -> impl WriteFlatBuffer<Target<'a> = fb::Footer<'a>> + FlatBufferRoot {
         FooterFlatBufferWriter {
@@ -183,7 +186,7 @@ impl Footer {
 pub(crate) struct FooterFlatBufferWriter {
     ctx: ArrayContext,
     layout: Layout,
-    segments: Arc<[Segment]>,
+    segments: Arc<[SegmentSpec]>,
     statistics: Option<Arc<[StatsSet]>>,
 }
 
@@ -200,7 +203,7 @@ impl WriteFlatBuffer for FooterFlatBufferWriter {
         let layout_ctx = LayoutContext::empty();
         let layout = self.layout.write_flatbuffer(fbb, &layout_ctx);
 
-        let segments = fbb.create_vector_from_iter(self.segments.iter().map(fb::Segment::from));
+        let segments = fbb.create_vector_from_iter(self.segments.iter().map(fb::SegmentSpec::from));
         let statistics = self
             .statistics
             .as_ref()

vortex-file/src/footer/postscript.rs

@@ -2,12 +2,12 @@ use flatbuffers::Follow;
 use vortex_error::{VortexError, vortex_err};
 use vortex_flatbuffers::{FlatBufferRoot, ReadFlatBuffer, WriteFlatBuffer, footer as fb};
 
-use crate::footer::segment::Segment;
+use crate::footer::segment::SegmentSpec;
 
 /// Captures the layout information of a Vortex file.
 pub(crate) struct Postscript {
-    pub(crate) dtype: Option<Segment>,
-    pub(crate) footer: Segment,
+    pub(crate) dtype: Option<SegmentSpec>,
+    pub(crate) footer: SegmentSpec,
 }
 
 impl FlatBufferRoot for Postscript {}
@@ -19,8 +19,8 @@ impl WriteFlatBuffer for Postscript {
         &self,
         fbb: &mut flatbuffers::FlatBufferBuilder<'fb>,
     ) -> flatbuffers::WIPOffset<Self::Target<'fb>> {
-        let dtype = self.dtype.as_ref().map(fb::Segment::from);
-        let footer = fb::Segment::from(&self.footer);
+        let dtype = self.dtype.as_ref().map(fb::SegmentSpec::from);
+        let footer = fb::SegmentSpec::from(&self.footer);
         fb::Postscript::create(
             fbb,
             &fb::PostscriptArgs {
@@ -39,8 +39,8 @@ impl ReadFlatBuffer for Postscript {
         fb: &<Self::Source<'buf> as Follow<'buf>>::Inner,
     ) -> Result<Self, Self::Error> {
         Ok(Self {
-            dtype: fb.dtype().map(Segment::try_from).transpose()?,
-            footer: Segment::try_from(
+            dtype: fb.dtype().map(SegmentSpec::try_from).transpose()?,
+            footer: SegmentSpec::try_from(
                 fb.footer()
                     .ok_or_else(|| vortex_err!("Postscript missing footer segment"))?,
             )?,

vortex-file/src/footer/segment.rs

@@ -4,22 +4,22 @@ use vortex_flatbuffers::footer as fb;
 
 /// The location of a segment within a Vortex file.
 #[derive(Clone, Debug)]
-pub struct Segment {
+pub struct SegmentSpec {
     pub offset: u64,
     pub length: u32,
     pub alignment: Alignment,
 }
 
-impl From<&Segment> for fb::Segment {
-    fn from(value: &Segment) -> Self {
-        fb::Segment::new(value.offset, value.length, value.alignment.exponent(), 0, 0)
+impl From<&SegmentSpec> for fb::SegmentSpec {
+    fn from(value: &SegmentSpec) -> Self {
+        fb::SegmentSpec::new(value.offset, value.length, value.alignment.exponent(), 0, 0)
     }
 }
 
-impl TryFrom<&fb::Segment> for Segment {
+impl TryFrom<&fb::SegmentSpec> for SegmentSpec {
     type Error = VortexError;
 
-    fn try_from(value: &fb::Segment) -> Result<Self, Self::Error> {
+    fn try_from(value: &fb::SegmentSpec) -> Result<Self, Self::Error> {
         Ok(Self {
             offset: value.offset(),
             length: value.length(),

vortex-file/src/generic.rs

@@ -19,7 +19,7 @@ use vortex_layout::scan::ScanDriver;
 use vortex_layout::segments::{AsyncSegmentReader, SegmentEvent, SegmentId, SegmentStream};
 use vortex_metrics::{Counter, VortexMetrics};
 
-use crate::footer::{Footer, Segment};
+use crate::footer::{Footer, SegmentSpec};
 use crate::segments::channel::SegmentChannel;
 use crate::segments::{InMemorySegmentCache, SegmentCache};
 use crate::{FileType, VortexOpenOptions};
@@ -344,20 +344,20 @@ where
 #[derive(Debug)]
 struct SegmentRequest {
     id: SegmentId,
-    location: Segment,
+    spec: SegmentSpec,
     cancel_handle: oneshot::Receiver<()>,
 }
 
 impl SegmentRequest {
-    fn new(id: SegmentId, location: Segment, cancel_handle: oneshot::Receiver<()>) -> Self {
+    fn new(id: SegmentId, spec: SegmentSpec, cancel_handle: oneshot::Receiver<()>) -> Self {
         Self {
             id,
-            location,
+            spec,
             cancel_handle,
         }
     }
     fn range(&self) -> Range<u64> {
-        self.location.offset..self.location.offset + self.location.length as u64
+        self.spec.offset..self.spec.offset + self.spec.length as u64
     }
 }
 
@@ -366,7 +366,7 @@ async fn filter_with_cache(
     cache: Arc<dyn SegmentCache>,
     inflight_segments: InflightSegments,
 ) -> Option<SegmentRequest> {
-    match cache.get(request.id, request.location.alignment).await {
+    match cache.get(request.id, request.spec.alignment).await {
         Ok(None) => {}
         Ok(Some(buffer)) => {
             inflight_segments.complete(request.id, Ok(buffer));
@@ -389,7 +389,7 @@ struct CoalescedSegmentRequest {
     /// The range of the file to read.
     pub(crate) byte_range: Range<u64>,
     /// The original segment requests, ordered by segment ID.
-    pub(crate) requests: Vec<(SegmentId, Segment)>,
+    pub(crate) requests: Vec<(SegmentId, SegmentSpec)>,
 }
 
 #[derive(Default)]
@@ -430,7 +430,7 @@ impl CoalescedCancellationHandle {
 async fn evaluate<R: VortexReadAt>(
     read: R,
     request: CoalescedSegmentRequest,
-    segment_map: Arc<[Segment]>,
+    segment_map: Arc<[SegmentSpec]>,
     segment_cache: Arc<dyn SegmentCache>,
     inflight_segments: InflightSegments,
 ) -> VortexResult<()> {
@@ -516,7 +516,7 @@ fn coalesce(
                     //  to ensure correct alignment for all coalesced buffers.
                     alignment: requests
                         .first()
-                        .map(|r| r.location.alignment)
+                        .map(|r| r.spec.alignment)
                         .unwrap_or(Alignment::none()),
                     byte_range: range.clone(),
                     requests: vec![],
@@ -531,9 +531,9 @@ fn coalesce(
         .collect::<Vec<_>>();
 
     for req in requests {
-        let idx = fetch_ranges.partition_point(|v| v.start <= req.location.offset) - 1;
+        let idx = fetch_ranges.partition_point(|v| v.start <= req.spec.offset) - 1;
         let (ref mut request, ref mut cancellation) = coalesced[idx];
-        request.requests.push((req.id, req.location));
+        request.requests.push((req.id, req.spec));
         cancellation.push(req.cancel_handle);
     }
 

vortex-file/src/lib.rs

@@ -105,7 +105,7 @@ mod writer;
 use std::sync::{Arc, LazyLock};
 
 pub use file::*;
-pub use footer::{Footer, Segment};
+pub use footer::{Footer, SegmentSpec};
 pub use forever_constant::*;
 pub use generic::*;
 pub use memory::*;

vortex-file/src/memory.rs

@@ -9,7 +9,7 @@ use vortex_layout::segments::{AsyncSegmentReader, SegmentId, SegmentStream};
 use vortex_metrics::VortexMetrics;
 
 use crate::segments::SegmentCache;
-use crate::{FileType, Footer, Segment, VortexOpenOptions};
+use crate::{FileType, Footer, SegmentSpec, VortexOpenOptions};
 
 /// A Vortex file that is backed by an in-memory buffer.
 ///
@@ -60,7 +60,7 @@ impl ScanDriver for InMemoryVortexFile {
 #[async_trait]
 impl AsyncSegmentReader for InMemoryVortexFile {
     async fn get(&self, id: SegmentId) -> VortexResult<ByteBuffer> {
-        let segment: &Segment = self
+        let segment: &SegmentSpec = self
             .footer
             .segment_map()
             .get(*id as usize)

vortex-file/src/open.rs

@@ -15,7 +15,7 @@ use vortex_layout::segments::SegmentId;
 use vortex_layout::{LayoutRegistry, LayoutRegistryExt};
 use vortex_metrics::VortexMetrics;
 
-use crate::footer::{Footer, Postscript, Segment};
+use crate::footer::{Footer, Postscript, SegmentSpec};
 use crate::segments::{NoOpSegmentCache, SegmentCache};
 use crate::{DEFAULT_REGISTRY, EOF_SIZE, MAGIC_BYTES, MAX_FOOTER_SIZE, VERSION, VortexFile};
 
@@ -272,7 +272,7 @@ impl<F: FileType> VortexOpenOptions<F> {
         &self,
         initial_offset: u64,
         initial_read: &ByteBuffer,
-        dtype: Segment,
+        dtype: SegmentSpec,
     ) -> VortexResult<DType> {
         let offset = usize::try_from(dtype.offset - initial_offset)?;
         let sliced_buffer =
@@ -287,7 +287,7 @@ impl<F: FileType> VortexOpenOptions<F> {
         &self,
         initial_offset: u64,
         initial_read: &ByteBuffer,
-        segment: Segment,
+        segment: SegmentSpec,
         dtype: DType,
     ) -> VortexResult<Footer> {
         let offset = usize::try_from(segment.offset - initial_offset)?;

vortex-file/src/segments/writer.rs

@@ -3,18 +3,19 @@ use vortex_error::{VortexResult, vortex_err};
 use vortex_io::VortexWrite;
 use vortex_layout::segments::{SegmentId, SegmentWriter};
 
-use crate::footer::Segment;
+use crate::footer::SegmentSpec;
 
 /// A segment writer that holds buffers in memory until they are flushed by a writer.
 #[derive(Default)]
 pub(crate) struct BufferedSegmentWriter {
-    segments: Vec<Vec<ByteBuffer>>,
+    /// A Vec byte buffers for segments
+    segments_buffers: Vec<Vec<ByteBuffer>>,
     next_id: SegmentId,
 }
 
 impl SegmentWriter for BufferedSegmentWriter {
     fn put(&mut self, data: &[ByteBuffer]) -> SegmentId {
-        self.segments.push(data.to_vec());
+        self.segments_buffers.push(data.to_vec());
         let id = self.next_id;
         self.next_id = SegmentId::from(*self.next_id + 1);
         id
@@ -25,10 +26,10 @@ impl BufferedSegmentWriter {
     /// Flush the segments to the provided async writer.
     pub async fn flush_async<W: VortexWrite>(
         &mut self,
-        write: &mut futures::io::Cursor<W>,
-        segments: &mut Vec<Segment>,
+        writer: &mut futures::io::Cursor<W>,
+        segment_descriptions: &mut Vec<SegmentSpec>,
     ) -> VortexResult<()> {
-        for buffers in self.segments.drain(..) {
+        for buffers in self.segments_buffers.drain(..) {
             // The API requires us to write these buffers contiguously. Therefore, we can only
             // respect the alignment of the first one.
             // Don't worry, in most cases the caller knows what they're doing and will align the
@@ -39,22 +40,22 @@ impl BufferedSegmentWriter {
                 .unwrap_or_else(Alignment::none);
 
             // Add any padding required to align the segment.
-            let offset = write.position();
+            let offset = writer.position();
             let padding = offset.next_multiple_of(*alignment as u64) - offset;
             if padding > 0 {
-                write
+                writer
                     .write_all(ByteBuffer::zeroed(padding as usize))
                     .await?;
             }
-            let offset = write.position();
+            let offset = writer.position();
 
             for buffer in buffers {
-                write.write_all(buffer).await?;
+                writer.write_all(buffer).await?;
             }
 
-            segments.push(Segment {
+            segment_descriptions.push(SegmentSpec {
                 offset,
-                length: u32::try_from(write.position() - offset)
+                length: u32::try_from(writer.position() - offset)
                     .map_err(|_| vortex_err!("segment length exceeds maximum u32"))?,
                 alignment,
             });