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