| // Licensed to the Apache Software Foundation (ASF) under one or more | |
| // contributor license agreements. See the NOTICE file distributed with | |
| // this work for additional information regarding copyright ownership. | |
| // The ASF licenses this file to You 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. | |
| //! Driver write coordination and task-local writers restored from serialized state, for batch | |
| //! writes and for the writes of micro-batches. | |
| use std::ffi::c_void; | |
| use arrow_array::{ffi, Array, RecordBatch, StructArray}; | |
| use arrow_data::ArrayData; | |
| use arrow_schema::{ArrowError, DataType, SchemaRef}; | |
| use serde::Serialize; | |
| use crate::abi::{self, ArrowArray, SparkDsTaskContext}; | |
| use crate::bridge::stream::validate_schema; | |
| use crate::bridge::{decode, describe, drop_provider, encode, provider_call}; | |
| use crate::{ | |
| AbortInfo, BatchWrite, CommitInfo, DataWriter, DataWriterFactory, PartitionWriter, Result, | |
| StreamingAbortInfo, StreamingCommitInfo, StreamingWrite, TaskContext, WriterContext, | |
| }; | |
| /// A batch write, which a driver writer drives as a streaming write whose epoch ID is always | |
| /// -1 and is ignored. | |
| pub struct Batch<W>(pub W); | |
| impl<W: BatchWrite> StreamingWrite for Batch<W> { | |
| type Factory = W::Factory; | |
| type Message = W::Message; | |
| fn new_writer_factory(&self) -> Result<W::Factory> { | |
| self.0.new_writer_factory() | |
| } | |
| fn commit(&mut self, info: StreamingCommitInfo<W::Message>) -> Result<()> { | |
| self.0.commit(CommitInfo::new(info.messages)) | |
| } | |
| fn abort(&mut self, info: StreamingAbortInfo<W::Message>) -> Result<()> { | |
| self.0.abort(AbortInfo::new(info.messages)) | |
| } | |
| } | |
| /// A driver writer that decodes its own commit messages, so that one handle type holds the | |
| /// driver writers of batch writes and of the writes of micro-batches, which share the writer | |
| /// handles of the ABI. | |
| pub trait DriverWrite: Send { | |
| fn commit(&mut self, epoch_id: i64, messages: &[Option<&[u8]>]) -> Result<()>; | |
| fn abort(&mut self, epoch_id: i64, messages: &[Option<&[u8]>]) -> Result<()>; | |
| } | |
| /// The driver keeps this coordinator until close, including after a failed commit, which | |
| /// Spark aborts next. Spark closes the writer right after it commits or aborts the write. | |
| pub struct DriverWriter<C: StreamingWrite> { | |
| coordinator: Option<C>, | |
| } | |
| impl<C: StreamingWrite> DriverWriter<C> { | |
| /// Wraps a coordinator, with the state that its task writers need: its serialized | |
| /// writer factory. On failure, the coordinator is dropped. | |
| pub fn create(coordinator: C) -> Result<(Box<dyn DriverWrite>, Vec<u8>)> { | |
| let writer = Self { | |
| coordinator: Some(coordinator), | |
| }; | |
| // The factory's destructor is connector code too, so it runs in provider_call. | |
| let state = provider_call(|| encode(&writer.coordinator().new_writer_factory()?))?; | |
| Ok((Box::new(writer), state)) | |
| } | |
| fn coordinator(&self) -> &C { | |
| self.coordinator.as_ref().expect("coordinator is present") | |
| } | |
| fn coordinator_mut(&mut self) -> &mut C { | |
| self.coordinator.as_mut().expect("coordinator is present") | |
| } | |
| } | |
| impl<C: StreamingWrite> DriverWrite for DriverWriter<C> { | |
| fn commit(&mut self, epoch_id: i64, messages: &[Option<&[u8]>]) -> Result<()> { | |
| let messages = messages | |
| .iter() | |
| .map(|message| decode(message.ok_or("missing committed task message")?)) | |
| .collect::<Result<Vec<_>>>()?; | |
| self.coordinator_mut() | |
| .commit(StreamingCommitInfo::new(epoch_id, messages)) | |
| } | |
| fn abort(&mut self, epoch_id: i64, messages: &[Option<&[u8]>]) -> Result<()> { | |
| // Abort is the cleanup path: a message that cannot be decoded is passed as None | |
| // instead of preventing the coordinator from cleaning up. | |
| let messages = messages | |
| .iter() | |
| .enumerate() | |
| .map(|(partition, message)| match decode((*message)?) { | |
| Ok(message) => Some(message), | |
| Err(error) => { | |
| log::warn!( | |
| "Aborting a write without the commit message of partition \ | |
| {partition}, which cannot be decoded: {}", | |
| describe(&*error) | |
| ); | |
| None | |
| } | |
| }) | |
| .collect(); | |
| self.coordinator_mut() | |
| .abort(StreamingAbortInfo::new(epoch_id, messages)) | |
| } | |
| } | |
| impl<C: StreamingWrite> Drop for DriverWriter<C> { | |
| fn drop(&mut self) { | |
| // A panic of the coordinator's Drop is logged instead of unwinding into close. | |
| if let Some(coordinator) = self.coordinator.take() { | |
| drop_provider(coordinator); | |
| } | |
| } | |
| } | |
| /// A task writer that encodes its own commit message, so that one handle type holds the | |
| /// writers of batch and streaming writes, whatever their messages. | |
| trait TaskWriter: Send { | |
| fn write(&mut self, batch: RecordBatch) -> Result<()>; | |
| fn commit(&mut self) -> Result<Vec<u8>>; | |
| fn abort(&mut self) -> Result<()>; | |
| } | |
| impl<M: Serialize> TaskWriter for PartitionWriter<'_, M> { | |
| fn write(&mut self, batch: RecordBatch) -> Result<()> { | |
| DataWriter::write(&mut **self, batch) | |
| } | |
| fn commit(&mut self) -> Result<Vec<u8>> { | |
| encode(&DataWriter::commit(&mut **self)?) | |
| } | |
| fn abort(&mut self) -> Result<()> { | |
| DataWriter::abort(&mut **self) | |
| } | |
| } | |
| struct TaskState<'task> { | |
| writer: Option<Box<dyn TaskWriter + 'task>>, | |
| // The struct type of the arrays that write gets: the schema that create_data_writer got. | |
| data_type: DataType, | |
| } | |
| impl TaskState<'_> { | |
| fn writer(&mut self) -> &mut (dyn TaskWriter + '_) { | |
| self.writer.as_deref_mut().expect("writer is present") | |
| } | |
| } | |
| impl Drop for TaskState<'_> { | |
| fn drop(&mut self) { | |
| if let Some(writer) = self.writer.take() { | |
| drop_provider(writer); | |
| } | |
| } | |
| } | |
| /// Restores the task writer of a batch write, with factory `B`, or of a micro-batch, with | |
| /// factory `S`, without creating or consulting any driver registry. The epoch ID tells them | |
| /// apart: it is -1 for a batch write. | |
| /// | |
| /// # Safety | |
| /// `task` must satisfy TaskContext::from_raw and remain valid until close_task. | |
| /// The returned handle must never be used concurrently, and must be closed exactly | |
| /// once while the plugin stays loaded. | |
| pub unsafe fn open<B: DataWriterFactory, S: DataWriterFactory>( | |
| task: *const SparkDsTaskContext, | |
| schema: SchemaRef, | |
| state: &[u8], | |
| epoch_id: i64, | |
| ) -> Result<*mut c_void> { | |
| match epoch_id { | |
| -1 => unsafe { open_writer::<B>(task, schema, state, None) }, | |
| epoch_id if epoch_id >= 0 => unsafe { | |
| open_writer::<S>(task, schema, state, Some(epoch_id)) | |
| }, | |
| _ => Err(format!("invalid epoch ID {epoch_id}").into()), | |
| } | |
| } | |
| /// # Safety | |
| /// As for open. | |
| unsafe fn open_writer<F: DataWriterFactory>( | |
| task: *const SparkDsTaskContext, | |
| schema: SchemaRef, | |
| state: &[u8], | |
| epoch_id: Option<i64>, | |
| ) -> Result<*mut c_void> { | |
| validate_schema(&schema)?; | |
| let factory: F = decode(state)?; | |
| let (task, partition_id) = unsafe { TaskContext::from_raw(task)? }; | |
| let data_type = DataType::Struct(schema.fields().clone()); | |
| let mut context = WriterContext::new(schema, partition_id, task); | |
| context.epoch_id = epoch_id; | |
| let opened = provider_call(|| factory.open(context)); | |
| // Keep guarded writer destruction in place before dropping the temporary | |
| // factory, whose destructor is connector code too. | |
| let state = opened.map(|writer| { | |
| Box::new(TaskState { | |
| writer: Some(Box::new(writer)), | |
| data_type, | |
| }) | |
| }); | |
| let factory_drop = provider_call(|| { | |
| drop(factory); | |
| Ok(()) | |
| }); | |
| let state = state?; | |
| factory_drop?; | |
| Ok(Box::into_raw(state).cast()) | |
| } | |
| /// # Safety | |
| /// `handle` must be a live handle from open, accessed without concurrency. | |
| unsafe fn task_state<'a>(handle: *mut c_void) -> Result<&'a mut TaskState<'a>> { | |
| abi::require_output(handle)?; | |
| Ok(unsafe { &mut *handle.cast::<TaskState<'a>>() }) | |
| } | |
| /// Imports owned Arrow data, with the schema of the writer, and passes it to the task writer. | |
| /// | |
| /// # Safety | |
| /// `handle` must follow open's contract. The array must be valid Arrow C data of the schema | |
| /// of the writer, which this call may move. | |
| pub unsafe fn write_batch(handle: *mut c_void, array: *mut ArrowArray) -> Result<()> { | |
| let state = unsafe { task_state(handle)? }; | |
| abi::require_output(array)?; | |
| let array = unsafe { import(ArrowArray::from_raw(array), &state.data_type)? }; | |
| if array.null_count() != 0 { | |
| return Err("write input cannot contain null rows".into()); | |
| } | |
| state.writer().write(RecordBatch::from(array)) | |
| } | |
| /// Imports a batch to write. Arrow does not validate the C data that it imports, which the safe | |
| /// accessors of the connector rely on, so this validates its layout and values: a Spark string | |
| /// may hold bytes that are not UTF-8, such as those of a cast from binary, which a Rust `&str` | |
| /// must not. It leaves nullability to Spark, for the reason that `validate` gives. Arrow requires | |
| /// each buffer of fixed-width values to be aligned to its type, such as the 16 bytes of an `i128` | |
| /// for a decimal on x86_64 and aarch64, which the Arrow Java allocator of Spark does not promise, | |
| /// so this copies the buffers that are not aligned, and only those. | |
| /// | |
| /// # Safety | |
| /// As for write_batch: the array must be Arrow C data of `data_type`. | |
| unsafe fn import(array: ArrowArray, data_type: &DataType) -> Result<StructArray> { | |
| let mut data = unsafe { ffi::from_ffi_and_data_type(array, data_type.clone())? }; | |
| data.align_buffers(); | |
| validate(&data).map_err(|e| format!("write input is not valid Arrow data: {e}"))?; | |
| Ok(StructArray::from(data)) | |
| } | |
| /// Validates `data` and its children as `ArrayData::validate_full` does, except that it does not | |
| /// check nulls against the nullability of fields. Arrow rejects any null in the child of a list | |
| /// or map whose element is not nullable, even one under a null slot, a layout that Spark accepts | |
| /// from a native scan: Spark checks nullability itself, masked by the parent, before it passes a | |
| /// batch to write. | |
| fn validate(data: &ArrayData) -> std::result::Result<(), ArrowError> { | |
| data.validate()?; | |
| if let Some(nulls) = data.nulls() { | |
| let actual = nulls.len() - nulls.inner().count_set_bits(); | |
| if actual != nulls.null_count() { | |
| return Err(ArrowError::InvalidArgumentError(format!( | |
| "null count {} does not match the {actual} nulls of the validity buffer", | |
| nulls.null_count() | |
| ))); | |
| } | |
| } | |
| data.validate_values()?; | |
| data.child_data().iter().try_for_each(validate) | |
| } | |
| /// Commits a task, and returns its serialized message. | |
| /// | |
| /// # Safety | |
| /// `handle` must follow open's contract. | |
| pub unsafe fn commit_task(handle: *mut c_void) -> Result<Vec<u8>> { | |
| unsafe { task_state(handle)? }.writer().commit() | |
| } | |
| /// Aborts a task, including after write or commit failures. | |
| /// | |
| /// # Safety | |
| /// `handle` must follow open's contract. | |
| pub unsafe fn abort_task(handle: *mut c_void) -> Result<()> { | |
| unsafe { task_state(handle)? }.writer().abort() | |
| } | |
| /// Releases a task writer without committing or aborting it implicitly. | |
| /// | |
| /// # Safety | |
| /// `handle` must follow open's contract and must not be used again. | |
| pub unsafe fn close_task(handle: *mut c_void) -> Result<()> { | |
| abi::require_output(handle)?; | |
| drop(unsafe { Box::from_raw(handle.cast::<TaskState<'_>>()) }); | |
| Ok(()) | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use std::sync::Arc; | |
| use arrow_array::builder::{ | |
| Int64BufferBuilder, Int64Builder, ListBuilder, MapBuilder, StringBuilder, | |
| }; | |
| use arrow_array::cast::AsArray; | |
| use arrow_array::ffi::FFI_ArrowArray; | |
| use arrow_array::types::{Decimal128Type, Int64Type}; | |
| use arrow_array::{ | |
| make_array, Array, ArrayRef, BinaryArray, Int64Array, ListArray, StringArray, StructArray, | |
| }; | |
| use arrow_data::ArrayData; | |
| use arrow_schema::{DataType, Field, Fields}; | |
| use super::import; | |
| /// String data whose second value is not UTF-8, which only unchecked construction builds. | |
| fn invalid_utf8() -> ArrayData { | |
| let bytes = BinaryArray::from_vec(vec![b"ok".as_slice(), [0xFFu8].as_slice()]); | |
| unsafe { | |
| bytes | |
| .to_data() | |
| .into_builder() | |
| .data_type(DataType::Utf8) | |
| .build_unchecked() | |
| } | |
| } | |
| /// Exports a batch of an ID column and the given label column, and imports it to write. | |
| fn import_batch(labels: ArrayData) -> crate::Result<StructArray> { | |
| let ids = Int64Array::from_iter_values(0..labels.len() as i64); | |
| let fields = Fields::from(vec![ | |
| Field::new("id", DataType::Int64, false), | |
| Field::new("label", labels.data_type().clone(), true), | |
| ]); | |
| let columns: Vec<ArrayRef> = vec![Arc::new(ids), make_array(labels)]; | |
| let batch = StructArray::try_new(fields, columns, None)?; | |
| import_data(&batch.to_data()) | |
| } | |
| /// Exports a batch and imports it to write, without checking it as an array would. | |
| fn import_data(batch: &ArrayData) -> crate::Result<StructArray> { | |
| unsafe { import(FFI_ArrowArray::new(batch), batch.data_type()) } | |
| } | |
| #[test] | |
| fn import_accepts_valid_strings() { | |
| let batch = import_batch(StringArray::from(vec!["ok", "fine"]).to_data()).unwrap(); | |
| assert_eq!(batch.column(0).as_primitive::<Int64Type>().value(1), 1); | |
| assert_eq!(batch.column(1).as_string::<i32>().value(1), "fine"); | |
| } | |
| #[test] | |
| fn import_rejects_strings_that_are_not_utf8() { | |
| let error = import_batch(invalid_utf8()).unwrap_err().to_string(); | |
| assert!(error.contains("not valid Arrow data"), "{error}"); | |
| assert!( | |
| error.contains("Invalid UTF8 sequence at string index 1"), | |
| "{error}" | |
| ); | |
| } | |
| #[test] | |
| fn import_rejects_nested_strings_that_are_not_utf8() { | |
| let mut labels = ListBuilder::new(StringBuilder::new()); | |
| labels.values().append_value("ok"); | |
| labels.values().append_value("x"); | |
| labels.append(true); | |
| let labels: ListArray = labels.finish(); | |
| let labels = labels | |
| .to_data() | |
| .into_builder() | |
| .child_data(vec![invalid_utf8()]); | |
| let error = import_batch(unsafe { labels.build_unchecked() }) | |
| .unwrap_err() | |
| .to_string(); | |
| assert!( | |
| error.contains("Invalid UTF8 sequence at string index 1"), | |
| "{error}" | |
| ); | |
| } | |
| #[test] | |
| fn import_accepts_nulls_under_null_slots_of_non_nullable_elements() { | |
| // [[1], null] of array<bigint not null>, where the null list still spans a null element, | |
| // as a native scan may return and Spark accepts. | |
| let mut labels = ListBuilder::new(Int64Builder::new()); | |
| labels.values().append_value(1); | |
| labels.append(true); | |
| labels.values().append_null(); | |
| labels.append(false); | |
| let labels: ListArray = labels.finish(); | |
| let element = Arc::new(Field::new("element", DataType::Int64, false)); | |
| let labels = labels | |
| .to_data() | |
| .into_builder() | |
| .data_type(DataType::List(element)); | |
| let batch = import_batch(unsafe { labels.build_unchecked() }).unwrap(); | |
| let labels = batch.column(1).as_list::<i32>(); | |
| assert!(labels.is_null(1)); | |
| assert_eq!(labels.value(0).as_primitive::<Int64Type>().value(0), 1); | |
| } | |
| #[test] | |
| fn import_accepts_nulls_under_null_slots_of_non_nullable_map_values() { | |
| // [{1: 10}, null] of map<bigint, bigint not null>, where the null map still spans an | |
| // entry with a null value. | |
| let mut labels = MapBuilder::new(None, Int64Builder::new(), Int64Builder::new()); | |
| labels.keys().append_value(1); | |
| labels.values().append_value(10); | |
| labels.append(true).unwrap(); | |
| labels.keys().append_value(2); | |
| labels.values().append_null(); | |
| labels.append(false).unwrap(); | |
| let labels = labels.finish().to_data(); | |
| let DataType::Map(entries, sorted) = labels.data_type().clone() else { | |
| unreachable!() | |
| }; | |
| let DataType::Struct(fields) = entries.data_type() else { | |
| unreachable!() | |
| }; | |
| let fields = Fields::from(vec![ | |
| fields[0].as_ref().clone(), | |
| fields[1].as_ref().clone().with_nullable(false), | |
| ]); | |
| let entries_data = labels.child_data()[0] | |
| .clone() | |
| .into_builder() | |
| .data_type(DataType::Struct(fields.clone())); | |
| let entries = entries | |
| .as_ref() | |
| .clone() | |
| .with_data_type(DataType::Struct(fields)); | |
| let labels = labels | |
| .into_builder() | |
| .data_type(DataType::Map(Arc::new(entries), sorted)) | |
| .child_data(vec![unsafe { entries_data.build_unchecked() }]); | |
| let batch = import_batch(unsafe { labels.build_unchecked() }).unwrap(); | |
| let labels = batch.column(1).as_map(); | |
| assert!(labels.is_null(1)); | |
| assert_eq!( | |
| labels | |
| .value(0) | |
| .column(1) | |
| .as_primitive::<Int64Type>() | |
| .value(0), | |
| 10 | |
| ); | |
| } | |
| #[test] | |
| fn import_rejects_a_struct_whose_child_is_shorter_than_it() { | |
| let ids = Int64Array::from_iter_values(0..1).to_data(); | |
| let fields = Fields::from(vec![Field::new("id", DataType::Int64, false)]); | |
| let batch = unsafe { | |
| ArrayData::builder(DataType::Struct(fields)) | |
| .len(2) | |
| .child_data(vec![ids]) | |
| .build_unchecked() | |
| }; | |
| let error = import_data(&batch).unwrap_err().to_string(); | |
| assert!(error.contains("not valid Arrow data"), "{error}"); | |
| assert!( | |
| error.contains("has length smaller than expected"), | |
| "{error}" | |
| ); | |
| } | |
| #[test] | |
| fn import_copies_decimal_values_that_are_not_aligned_to_i128() { | |
| // The decimals [123.45, -0.01], as the low and high halves of each value, eight bytes | |
| // into an allocation of a buffer builder, which is aligned to at least 32 bytes. | |
| let mut words = Int64BufferBuilder::new(5); | |
| words.append_slice(&[0, 12345, 0, -1, -1]); | |
| let values = words.finish().slice(8); | |
| let decimal = DataType::Decimal128(10, 2); | |
| let prices = unsafe { | |
| ArrayData::builder(decimal.clone()) | |
| .len(2) | |
| .add_buffer(values) | |
| .build_unchecked() | |
| }; | |
| let fields = Fields::from(vec![Field::new("price", decimal, false)]); | |
| let batch = unsafe { | |
| ArrayData::builder(DataType::Struct(fields)) | |
| .len(2) | |
| .child_data(vec![prices]) | |
| .build_unchecked() | |
| }; | |
| let batch = import_data(&batch).unwrap(); | |
| let prices = batch.column(0).as_primitive::<Decimal128Type>(); | |
| let alignment = align_of::<i128>(); | |
| assert_eq!(prices.values().inner().as_ptr().align_offset(alignment), 0); | |
| assert_eq!(prices.value(0), 12345); | |
| assert_eq!(prices.value(1), -1); | |
| } | |
| #[test] | |
| fn import_rejects_a_null_count_that_disagrees_with_the_validity_buffer() { | |
| let labels = Int64Array::from(vec![Some(1), None, Some(3)]); | |
| let validity = labels.nulls().unwrap().buffer().clone(); | |
| let labels = labels | |
| .to_data() | |
| .into_builder() | |
| .nulls(None) | |
| .null_bit_buffer(Some(validity)) | |
| .null_count(2); | |
| let error = import_batch(unsafe { labels.build_unchecked() }) | |
| .unwrap_err() | |
| .to_string(); | |
| assert!( | |
| error.contains("null count 2 does not match the 1 nulls of the validity buffer"), | |
| "{error}" | |
| ); | |
| } | |
| } |