Skip to main content

polars_io/external_reader/
ffi.rs

1//! A file reader builder of an I/O plugin (`polars.io_plugin.file_reader.v1`).
2use std::fmt;
3use std::hash::{Hash, Hasher};
4
5use polars_error::{PolarsResult, polars_err};
6use polars_io_ext_ffi::common::{FfiBuf, FfiSlice};
7use polars_io_ext_ffi::file_reader_v1::{BuilderHandle, Capabilities, Plugin};
8use polars_utils::aliases::PlIndexMap;
9use polars_utils::pl_str::PlSmallStr;
10
11use crate::io_plugin_ffi::{ffi_err_to_polars, file_reader_v1};
12
13/// One reference to a builder handle of the plugin `package`.
14pub struct FfiFileReaderBuilder {
15    package: PlSmallStr,
16    plugin: &'static Plugin,
17    handle: BuilderHandle,
18}
19
20// The contract makes builder handles thread-safe.
21unsafe impl Send for FfiFileReaderBuilder {}
22unsafe impl Sync for FfiFileReaderBuilder {}
23
24impl FfiFileReaderBuilder {
25    /// Takes ownership of one reference to `handle`, a builder of `package`.
26    ///
27    /// If `package`'s `file_reader.v1` contract can't be loaded, there is no release function to
28    /// call: the reference is leaked (the error says so).
29    ///
30    /// # Safety
31    /// `handle` must be a live builder handle of `package`'s `file_reader.v1` contract.
32    pub unsafe fn from_owned_handle(
33        package: PlSmallStr,
34        handle: BuilderHandle,
35    ) -> PolarsResult<Self> {
36        let plugin = file_reader_v1(&package).map_err(|e| {
37            e.wrap_msg(|m| format!("{m} (a file reader builder of {package} was leaked)"))
38        })?;
39        Ok(Self {
40            package,
41            plugin,
42            handle,
43        })
44    }
45
46    pub fn package(&self) -> &PlSmallStr {
47        &self.package
48    }
49
50    pub fn plugin(&self) -> &'static Plugin {
51        self.plugin
52    }
53
54    pub fn handle(&self) -> BuilderHandle {
55        self.handle
56    }
57
58    pub fn name(&self) -> PlSmallStr {
59        let name: FfiBuf = unsafe { (self.plugin.builder_name)(self.handle) };
60        name.to_string_lossy().into()
61    }
62
63    pub fn fingerprint(&self) -> u64 {
64        unsafe { (self.plugin.builder_fingerprint)(self.handle) }
65    }
66
67    pub fn capabilities(&self) -> PolarsResult<Capabilities> {
68        unsafe { (self.plugin.builder_capabilities)(self.handle) }
69            .into_result()
70            .map_err(|e| ffi_err_to_polars(e, &self.package))
71    }
72
73    pub fn explain_properties(&self) -> PolarsResult<PlIndexMap<String, String>> {
74        let props = unsafe { (self.plugin.builder_explain)(self.handle) }
75            .into_result()
76            .map_err(|e| ffi_err_to_polars(e, &self.package))?;
77        Ok(props
78            .as_slice()
79            .chunks_exact(2)
80            .map(|kv| (kv[0].to_string_lossy(), kv[1].to_string_lossy()))
81            .collect())
82    }
83
84    fn serialize_bytes(&self) -> PolarsResult<FfiBuf> {
85        unsafe { (self.plugin.builder_serialize)(self.handle) }
86            .into_result()
87            .map_err(|e| ffi_err_to_polars(e, &self.package))
88    }
89
90    fn deserialize_bytes(package: PlSmallStr, bytes: &[u8]) -> PolarsResult<Self> {
91        let plugin = file_reader_v1(&package)?;
92        let handle = unsafe { (plugin.builder_deserialize)(FfiSlice::new(bytes)) }
93            .into_result()
94            .map_err(|e| ffi_err_to_polars(e, &package))?;
95        Ok(Self {
96            package,
97            plugin,
98            handle,
99        })
100    }
101}
102
103impl Clone for FfiFileReaderBuilder {
104    fn clone(&self) -> Self {
105        Self {
106            package: self.package.clone(),
107            plugin: self.plugin,
108            handle: unsafe { (self.plugin.builder_clone)(self.handle) },
109        }
110    }
111}
112
113impl Drop for FfiFileReaderBuilder {
114    fn drop(&mut self) {
115        unsafe { (self.plugin.builder_release)(self.handle) }
116    }
117}
118
119impl fmt::Debug for FfiFileReaderBuilder {
120    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
121        f.debug_struct("FfiFileReaderBuilder")
122            .field("package", &self.package)
123            .field("name", &self.name())
124            .finish()
125    }
126}
127
128/// Builders of one plugin with the same fingerprint read the same data.
129impl PartialEq for FfiFileReaderBuilder {
130    fn eq(&self, other: &Self) -> bool {
131        self.package == other.package && self.fingerprint() == other.fingerprint()
132    }
133}
134
135impl Eq for FfiFileReaderBuilder {}
136
137impl Hash for FfiFileReaderBuilder {
138    fn hash<H: Hasher>(&self, state: &mut H) {
139        self.package.hash(state);
140        self.fingerprint().hash(state);
141    }
142}
143
144#[cfg(feature = "serde")]
145mod _serde {
146    use polars_utils::pl_serialize::PackageBytes;
147    use serde::{Deserialize, Deserializer, Serialize, Serializer};
148
149    use super::*;
150
151    impl Serialize for FfiFileReaderBuilder {
152        fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
153            use serde::ser::Error;
154            let bytes = self.serialize_bytes().map_err(S::Error::custom)?;
155            PackageBytes {
156                package: self.package.clone(),
157                bytes: bytes.to_vec(),
158            }
159            .serialize(serializer)
160        }
161    }
162
163    impl<'de> Deserialize<'de> for FfiFileReaderBuilder {
164        fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
165            use serde::de::Error;
166            let s = PackageBytes::deserialize(deserializer)?;
167            Self::deserialize_bytes(s.package, &s.bytes)
168                .map_err(|e| D::Error::custom(polars_err!(ComputeError: "{e}")))
169        }
170    }
171}