1use crate::SQLError;
10use uqa_core::{
11 memory::{Produced, ProductionControl, ProductionVec},
12 Value,
13};
14
15use crate::ast::ColumnType;
16
17mod record;
18pub use record::create_record_parameter_with_control;
19mod range;
20pub use range::{
21 create_multirange_parameter_with_control, create_range_parameter_with_control,
22 RangeParameterBounds,
23};
24mod array;
25mod input;
26pub use array::create_array_parameter_with_control;
27pub use input::create_typed_parameter_with_control;
28mod binding;
29mod packed;
30mod tensor;
31pub use binding::{
32 bind_declared_parameter_types, bind_parameter_type_with_control, bind_parameter_types,
33};
34pub use tensor::SQLTensor;
35
36#[derive(Debug, Clone)]
38pub enum SQLParam {
39 Scalar(Value),
40 TypedScalar {
42 value: Value,
43 ty: ColumnType,
44 },
45 #[doc(hidden)]
48 DeferredError {
49 ty: ColumnType,
50 error: Box<crate::ast::DeferredSQLError>,
51 },
52 Vector(Vec<f32>),
53 Tensor(Vec<Vec<f32>>),
54 TypedTensor(SQLTensor),
56}
57
58impl SQLParam {
59 pub fn clone_with_control(
61 &self,
62 control: &ProductionControl<'_>,
63 ) -> Result<Produced<Self>, SQLError> {
64 crate::plan::copy::copy_syntax_with_control(self, control)
65 }
66
67 pub fn scalar(value: Value) -> Self {
68 Self::Scalar(value)
69 }
70
71 #[must_use]
72 pub fn typed_scalar(value: Value, ty: ColumnType) -> Self {
73 Self::TypedScalar { value, ty }
74 }
75
76 #[must_use]
78 pub fn scalar_value(&self) -> Option<&Value> {
79 match self {
80 Self::Scalar(value) | Self::TypedScalar { value, .. } => Some(value),
81 Self::Vector(_)
82 | Self::Tensor(_)
83 | Self::TypedTensor(_)
84 | Self::DeferredError { .. } => None,
85 }
86 }
87
88 #[must_use]
90 pub fn declared_scalar_type(&self) -> Option<&ColumnType> {
91 match self {
92 Self::TypedScalar { ty, .. } | Self::DeferredError { ty, .. } => Some(ty),
93 Self::Scalar(_) | Self::Vector(_) | Self::Tensor(_) | Self::TypedTensor(_) => None,
94 }
95 }
96
97 pub fn to_value(&self) -> Result<Value, SQLError> {
99 self.to_value_with_control(&ProductionControl::uncontrolled())
100 .map(|value| value.into_uncontrolled().expect("ordinary parameter value"))
101 }
102
103 pub fn to_value_with_control(
105 &self,
106 control: &ProductionControl<'_>,
107 ) -> Result<Produced<Value>, SQLError> {
108 control.check()?;
109 match self {
110 Self::DeferredError { error, .. } => Err((**error).clone().into()),
111 Self::Scalar(value) | Self::TypedScalar { value, .. } => Ok(control.copy_value(value)?),
112 Self::Vector(values) => vector_value(values, control),
113 Self::Tensor(vectors) => {
114 let mut output = ProductionVec::new(*control);
115 output.reserve(vectors.len())?;
116 for values in vectors {
117 output.push_produced(vector_value(values, control)?)?;
118 }
119 let (values, memory) = output.finish()?.into_parts();
120 Ok(control.finish(Value::List(values), memory)?)
121 }
122 Self::TypedTensor(tensor) => tensor.to_value_with_control(control),
123 }
124 }
125
126 pub fn vector(v: Vec<f32>) -> Self {
127 Self::Vector(v)
128 }
129
130 pub fn vector_with_control(
132 values: &[f32],
133 control: &ProductionControl<'_>,
134 ) -> Result<Produced<Self>, SQLError> {
135 control.check()?;
136 if values.is_empty() || u32::try_from(values.len()).is_err() {
137 return Err(SQLError::TypeMismatch(
138 "vector dimension must be a positive 32-bit integer".into(),
139 ));
140 }
141 for value in values {
142 crate::expr::vector_element_with_control(&Value::Float(f64::from(*value)), control)?;
143 }
144 let mut output = ProductionVec::new(*control);
145 output.extend_from_slice(values)?;
146 let (values, memory) = output.finish()?.into_parts();
147 Ok(control.finish(Self::Vector(values), memory)?)
148 }
149
150 pub fn tensor(v: Vec<Vec<f32>>) -> Self {
151 Self::Tensor(v)
152 }
153}
154
155fn vector_value(
156 values: &[f32],
157 control: &ProductionControl<'_>,
158) -> Result<Produced<Value>, SQLError> {
159 let mut output = ProductionVec::new(*control);
160 output.reserve(values.len())?;
161 for value in values {
162 output.push_produced(
163 control.finish(Value::Float(f64::from(*value)), control.empty_reservation())?,
164 )?;
165 }
166 let (values, memory) = output.finish()?.into_parts();
167 Ok(control.finish(Value::List(values), memory)?)
168}
169
170#[cfg(test)]
171mod tests {
172 use super::*;
173
174 #[test]
175 fn deferred_parameter_keeps_scalar_carriers_compact_and_errors_lazy() {
176 assert!(size_of::<SQLParam>() <= size_of::<(Value, ColumnType, usize)>());
177 let error = crate::plpgsql::runtime_diagnostics::unassigned_record("r");
178 let parameter = SQLParam::DeferredError {
179 ty: ColumnType::SmallInteger,
180 error: Box::new((&error).into()),
181 };
182 assert_eq!(parameter.scalar_value(), None);
183 assert_eq!(
184 parameter.declared_scalar_type(),
185 Some(&ColumnType::SmallInteger)
186 );
187 let observed = parameter.to_value().unwrap_err();
188 assert_eq!(observed.sqlstate(), error.sqlstate());
189 assert_eq!(observed.to_string(), error.to_string());
190 assert_eq!(observed.detail(), error.detail());
191 assert_eq!(observed.hint(), error.hint());
192 }
193
194 #[test]
195 fn typed_scalar_preserves_declared_type_without_changing_scalar_access() {
196 let value = Value::Int(7);
197 let typed = SQLParam::typed_scalar(value.clone(), ColumnType::SmallInteger);
198 assert_eq!(typed.scalar_value(), Some(&value));
199 assert_eq!(
200 typed.declared_scalar_type(),
201 Some(&ColumnType::SmallInteger)
202 );
203
204 let scalar = SQLParam::scalar(value.clone());
205 assert_eq!(scalar.scalar_value(), Some(&value));
206 assert_eq!(scalar.declared_scalar_type(), None);
207 }
208
209 #[test]
210 fn host_vector_input_checks_shape_and_finiteness_before_retaining_bytes() {
211 use uqa_core::{memory::MemoryBudget, CancellationToken};
212 let budget = MemoryBudget::new(64);
213 let original = CancellationToken::new();
214 let invoking = CancellationToken::new();
215 let control = ProductionControl::new(&budget, &original, &invoking);
216 let held = control.copy_text("held").unwrap();
217 for values in [
218 vec![],
219 vec![f32::NAN],
220 vec![f32::INFINITY],
221 vec![f32::NEG_INFINITY],
222 ] {
223 assert!(SQLParam::vector_with_control(&values, &control).is_err());
224 assert_eq!(budget.used(), held.reserved_bytes());
225 }
226 assert_eq!(
227 SQLParam::vector_with_control(&[1.0; 64], &control)
228 .unwrap_err()
229 .sqlstate(),
230 Some("53200")
231 );
232 assert_eq!(budget.used(), held.reserved_bytes());
233 for token in [&original, &invoking] {
234 token.cancel();
235 assert_eq!(
236 SQLParam::vector_with_control(&[1.0], &control)
237 .unwrap_err()
238 .sqlstate(),
239 Some("57014")
240 );
241 assert_eq!(budget.used(), held.reserved_bytes());
242 token.reset();
243 }
244 let mut input = [-0.0, f32::MIN_POSITIVE, f32::MAX];
245 let vector = SQLParam::vector_with_control(&input, &control).unwrap();
246 input[1] = 1.0;
247 assert_eq!(input[1], 1.0);
248 let SQLParam::Vector(values) = &*vector else {
249 panic!("expected dedicated vector");
250 };
251 assert_eq!(values[0].to_bits(), (-0.0_f32).to_bits());
252 assert_eq!(values[1], f32::MIN_POSITIVE);
253 assert_eq!(values[2], f32::MAX);
254 assert_eq!(
255 budget.used(),
256 held.reserved_bytes() + vector.reserved_bytes()
257 );
258 drop(vector);
259 assert_eq!(budget.used(), held.reserved_bytes());
260 }
261
262 #[test]
263 fn parameter_value_owners_keep_tensor_and_scalar_payloads_until_drop() {
264 use uqa_core::{memory::MemoryBudget, CancellationToken};
265 let budget = MemoryBudget::new(1 << 16);
266 let token = CancellationToken::new();
267 let control = ProductionControl::new(&budget, &token, &token);
268 for (parameter, expected) in [
269 (
270 SQLParam::typed_scalar(Value::Str("payload".repeat(32)), ColumnType::Text),
271 Value::Str("payload".repeat(32)),
272 ),
273 (
274 SQLParam::Vector(vec![1.0, 2.5]),
275 Value::List(vec![Value::Float(1.0), Value::Float(2.5)]),
276 ),
277 (
278 SQLParam::Tensor(vec![vec![1.0, 2.5], vec![]]),
279 Value::List(vec![
280 Value::List(vec![Value::Float(1.0), Value::Float(2.5)]),
281 Value::List(vec![]),
282 ]),
283 ),
284 ] {
285 let value = parameter.to_value_with_control(&control).unwrap();
286 assert_eq!(*value, expected);
287 assert!(value.reserved_bytes() > 0);
288 assert_eq!(budget.used(), value.reserved_bytes());
289 drop(value);
290 assert_eq!(budget.used(), 0);
291 assert_eq!(parameter.to_value().unwrap(), expected);
292 }
293 }
294
295 #[test]
296 fn parameter_production_releases_partial_output_on_quota_and_both_tokens() {
297 use uqa_core::{memory::MemoryBudget, CancellationToken};
298 let budget = MemoryBudget::new(256);
299 let original = CancellationToken::new();
300 let invoking = CancellationToken::new();
301 let control = ProductionControl::new(&budget, &original, &invoking);
302 let held = control.copy_text("held").unwrap();
303 let parameter = SQLParam::Tensor(vec![vec![1.0; 64], vec![2.0; 64]]);
304 assert_eq!(
305 parameter
306 .to_value_with_control(&control)
307 .unwrap_err()
308 .sqlstate(),
309 Some("53200")
310 );
311 assert_eq!(budget.used(), held.reserved_bytes());
312 for token in [&original, &invoking] {
313 token.cancel();
314 assert_eq!(
315 parameter
316 .to_value_with_control(&control)
317 .unwrap_err()
318 .sqlstate(),
319 Some("57014")
320 );
321 assert_eq!(budget.used(), held.reserved_bytes());
322 token.reset();
323 }
324 assert_eq!(
325 parameter.to_value().unwrap(),
326 Value::List(vec![
327 Value::List(vec![Value::Float(1.0); 64]),
328 Value::List(vec![Value::Float(2.0); 64])
329 ])
330 );
331 }
332}