fory_core/
context.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use crate::buffer::{Reader, Writer};
19use crate::config::Config;
20use std::collections::HashMap;
21use std::mem;
22
23use crate::error::Error;
24use crate::meta::MetaString;
25use crate::resolver::meta_resolver::{MetaReaderResolver, MetaWriterResolver};
26use crate::resolver::meta_string_resolver::{MetaStringReaderResolver, MetaStringWriterResolver};
27use crate::resolver::{RefReader, RefWriter};
28use crate::resolver::{TypeInfo, TypeResolver};
29use crate::serializer::StructSerializer;
30use crate::type_id as types;
31use crate::TypeId;
32use std::rc::Rc;
33
34/// Thread-local context cache with fast path for single Fory instance.
35/// Uses (cached_id, context) for O(1) access when using same Fory instance repeatedly.
36/// Falls back to HashMap for multiple Fory instances per thread.
37pub struct ContextCache<T> {
38    /// Fast path: cached context for the most recently used Fory instance
39    cached_id: u64,
40    cached_context: Option<Box<T>>,
41    /// Slow path: HashMap for other Fory instances
42    others: HashMap<u64, Box<T>>,
43}
44
45impl<T> ContextCache<T> {
46    pub fn new() -> Self {
47        ContextCache {
48            cached_id: u64::MAX,
49            cached_context: None,
50            others: HashMap::new(),
51        }
52    }
53
54    #[inline(always)]
55    pub fn get_or_insert(&mut self, id: u64, create: impl FnOnce() -> Box<T>) -> &mut T {
56        if self.cached_id == id {
57            // Fast path: same Fory instance as last time
58            return self.cached_context.as_mut().unwrap();
59        }
60
61        // Check if we need to swap with cached
62        if self.cached_context.is_some() {
63            // Move current cached to others
64            let old_id = self.cached_id;
65            let old_context = self.cached_context.take().unwrap();
66            self.others.insert(old_id, old_context);
67        }
68
69        // Get or create context for new id
70        let context = self.others.remove(&id).unwrap_or_else(create);
71        self.cached_id = id;
72        self.cached_context = Some(context);
73        self.cached_context.as_mut().unwrap()
74    }
75
76    /// Like `get_or_insert`, but the create closure returns a Result.
77    /// This allows error handling during context creation without pre-fetching resources.
78    #[inline(always)]
79    pub fn get_or_insert_result<E>(
80        &mut self,
81        id: u64,
82        create: impl FnOnce() -> Result<Box<T>, E>,
83    ) -> Result<&mut T, E> {
84        if self.cached_id == id {
85            // Fast path: same Fory instance as last time
86            return Ok(self.cached_context.as_mut().unwrap());
87        }
88
89        // Check if we need to swap with cached
90        if self.cached_context.is_some() {
91            // Move current cached to others
92            let old_id = self.cached_id;
93            let old_context = self.cached_context.take().unwrap();
94            self.others.insert(old_id, old_context);
95        }
96
97        // Get or create context for new id
98        let context = match self.others.remove(&id) {
99            Some(ctx) => ctx,
100            None => create()?,
101        };
102        self.cached_id = id;
103        self.cached_context = Some(context);
104        Ok(self.cached_context.as_mut().unwrap())
105    }
106}
107
108impl<T> Default for ContextCache<T> {
109    fn default() -> Self {
110        Self::new()
111    }
112}
113
114/// Serialization state container used on a single thread at a time.
115/// Sharing the same instance across threads simultaneously causes undefined behavior.
116#[allow(clippy::needless_lifetimes)]
117pub struct WriteContext<'a> {
118    // Replicated environment fields (direct access, no Arc indirection for flags)
119    type_resolver: TypeResolver,
120    compatible: bool,
121    share_meta: bool,
122    compress_string: bool,
123    xlang: bool,
124    check_struct_version: bool,
125    track_ref: bool,
126
127    // Context-specific fields
128    default_writer: Option<Writer<'a>>,
129    pub writer: Writer<'a>,
130    meta_resolver: MetaWriterResolver,
131    meta_string_resolver: MetaStringWriterResolver,
132    pub ref_writer: RefWriter,
133}
134
135#[allow(clippy::needless_lifetimes)]
136impl<'a> WriteContext<'a> {
137    pub fn new(type_resolver: TypeResolver, config: Config) -> WriteContext<'a> {
138        WriteContext {
139            type_resolver,
140            compatible: config.compatible,
141            share_meta: config.share_meta,
142            compress_string: config.compress_string,
143            xlang: config.xlang,
144            check_struct_version: config.check_struct_version,
145            track_ref: config.track_ref,
146            default_writer: None,
147            writer: Writer::from_buffer(Self::get_leak_buffer()),
148            meta_resolver: MetaWriterResolver::default(),
149            meta_string_resolver: MetaStringWriterResolver::default(),
150            ref_writer: RefWriter::new(),
151        }
152    }
153
154    #[inline(always)]
155    fn get_leak_buffer() -> &'static mut Vec<u8> {
156        Box::leak(Box::new(vec![]))
157    }
158
159    #[inline(always)]
160    pub fn attach_writer(&mut self, writer: Writer<'a>) {
161        let old = mem::replace(&mut self.writer, writer);
162        self.default_writer = Some(old);
163    }
164
165    #[inline(always)]
166    pub fn detach_writer(&mut self) {
167        let default = mem::take(&mut self.default_writer);
168        self.writer = default.unwrap();
169    }
170
171    /// Get type resolver
172    #[inline(always)]
173    pub fn get_type_resolver(&self) -> &TypeResolver {
174        &self.type_resolver
175    }
176
177    #[inline(always)]
178    pub fn get_type_info(&self, type_id: &std::any::TypeId) -> Result<Rc<TypeInfo>, Error> {
179        self.type_resolver.get_type_info(type_id)
180    }
181
182    /// Check if compatible mode is enabled
183    #[inline(always)]
184    pub fn is_compatible(&self) -> bool {
185        self.compatible
186    }
187
188    /// Check if meta sharing is enabled
189    #[inline(always)]
190    pub fn is_share_meta(&self) -> bool {
191        self.share_meta
192    }
193
194    /// Check if string compression is enabled
195    #[inline(always)]
196    pub fn is_compress_string(&self) -> bool {
197        self.compress_string
198    }
199
200    /// Check if xlang mode is enabled
201    #[inline(always)]
202    pub fn is_xlang(&self) -> bool {
203        self.xlang
204    }
205
206    /// Check if class version checking is enabled
207    #[inline(always)]
208    pub fn is_check_struct_version(&self) -> bool {
209        self.check_struct_version
210    }
211
212    /// Check if reference tracking is enabled
213    #[inline(always)]
214    pub fn is_track_ref(&self) -> bool {
215        self.track_ref
216    }
217
218    /// Write type meta inline using streaming protocol.
219    /// Writes index marker with LSB indicating new type or reference.
220    #[inline(always)]
221    pub fn write_type_meta(&mut self, type_id: std::any::TypeId) -> Result<(), Error> {
222        self.meta_resolver
223            .write_type_meta(&mut self.writer, type_id, &self.type_resolver)
224    }
225
226    /// Write generated struct type info without Rust TypeId hash lookups.
227    #[inline(always)]
228    pub fn write_struct_type_info<T: StructSerializer>(&mut self) -> Result<(), Error> {
229        let rust_type_id = std::any::TypeId::of::<T>();
230        let type_index = T::fory_type_index();
231        let type_id = self.type_resolver.get_type_id_by_index(type_index)?;
232        match type_id {
233            TypeId::STRUCT | TypeId::ENUM | TypeId::EXT | TypeId::TYPED_UNION => {
234                self.writer.write_u8(type_id as u8);
235                let user_type_id = self
236                    .type_resolver
237                    .get_user_type_id_by_index(&rust_type_id, type_index)?;
238                self.writer.write_var_u32(user_type_id);
239            }
240            TypeId::COMPATIBLE_STRUCT | TypeId::NAMED_COMPATIBLE_STRUCT => {
241                self.writer.write_u8(type_id as u8);
242                self.meta_resolver.write_type_meta_fast(
243                    &mut self.writer,
244                    rust_type_id,
245                    type_index,
246                    &self.type_resolver,
247                )?;
248            }
249            TypeId::NAMED_ENUM | TypeId::NAMED_EXT | TypeId::NAMED_STRUCT | TypeId::NAMED_UNION
250                if self.is_share_meta() =>
251            {
252                self.writer.write_u8(type_id as u8);
253                self.meta_resolver.write_type_meta_fast(
254                    &mut self.writer,
255                    rust_type_id,
256                    type_index,
257                    &self.type_resolver,
258                )?;
259            }
260            _ => {
261                self.write_any_type_info(type_id as u32, rust_type_id)?;
262            }
263        }
264        Ok(())
265    }
266
267    pub fn write_any_type_info(
268        &mut self,
269        fory_type_id: u32,
270        concrete_type_id: std::any::TypeId,
271    ) -> Result<Rc<TypeInfo>, Error> {
272        if types::is_internal_type(fory_type_id) {
273            self.writer.write_u8(fory_type_id as u8);
274            return self
275                .type_resolver
276                .get_type_info_by_id(fory_type_id)
277                .ok_or_else(|| Error::type_error("Type info for internal type not found"));
278        }
279        let type_info = self.type_resolver.get_type_info(&concrete_type_id)?;
280        let fory_type_id = type_info.get_type_id();
281        let namespace = type_info.get_namespace();
282        let type_name = type_info.get_type_name();
283        self.writer.write_u8(fory_type_id as u8);
284        // should be compiled to jump table generation
285        match fory_type_id {
286            TypeId::ENUM | TypeId::STRUCT | TypeId::EXT | TypeId::TYPED_UNION => {
287                let user_type_id = type_info.get_user_type_id();
288                self.writer.write_var_u32(user_type_id);
289            }
290            TypeId::COMPATIBLE_STRUCT | TypeId::NAMED_COMPATIBLE_STRUCT => {
291                // Write type meta inline using streaming protocol
292                self.meta_resolver.write_type_meta(
293                    &mut self.writer,
294                    concrete_type_id,
295                    &self.type_resolver,
296                )?;
297            }
298            TypeId::NAMED_ENUM | TypeId::NAMED_EXT | TypeId::NAMED_STRUCT | TypeId::NAMED_UNION => {
299                if self.is_share_meta() {
300                    // Write type meta inline using streaming protocol
301                    self.meta_resolver.write_type_meta(
302                        &mut self.writer,
303                        concrete_type_id,
304                        &self.type_resolver,
305                    )?;
306                } else {
307                    self.write_meta_string_bytes(namespace)?;
308                    self.write_meta_string_bytes(type_name)?;
309                }
310            }
311            _ => {
312                // default case: do nothing
313            }
314        }
315        Ok(type_info)
316    }
317
318    #[inline(always)]
319    pub fn write_meta_string_bytes(&mut self, ms: Rc<MetaString>) -> Result<(), Error> {
320        self.meta_string_resolver
321            .write_meta_string_bytes(&mut self.writer, ms)
322    }
323
324    #[inline(always)]
325    pub fn reset(&mut self) {
326        self.meta_resolver.reset();
327        self.meta_string_resolver.reset();
328        self.ref_writer.reset();
329    }
330}
331
332#[allow(clippy::needless_lifetimes)]
333impl<'a> Drop for WriteContext<'a> {
334    fn drop(&mut self) {
335        unsafe {
336            drop(Box::from_raw(self.writer.bf));
337        }
338    }
339}
340
341// Safety: WriteContext is only shared across threads via higher-level pooling code that
342// ensures single-threaded access while the context is in use. Users must never hold the same
343// instance on multiple threads simultaneously; that would violate the invariants and result in
344// undefined behavior. Under that assumption, marking it Send/Sync is sound.
345#[allow(clippy::needless_lifetimes)]
346unsafe impl<'a> Send for WriteContext<'a> {}
347#[allow(clippy::needless_lifetimes)]
348unsafe impl<'a> Sync for WriteContext<'a> {}
349
350/// Deserialization state container used on a single thread at a time.
351/// Sharing the same instance across threads simultaneously causes undefined behavior.
352pub struct ReadContext<'a> {
353    // Replicated environment fields (direct access, no Arc indirection for flags)
354    type_resolver: TypeResolver,
355    config: Config,
356    compatible: bool,
357    share_meta: bool,
358    xlang: bool,
359    max_dyn_depth: u32,
360    check_struct_version: bool,
361    check_string_read: bool,
362
363    // Context-specific fields
364    pub reader: Reader<'a>,
365    pub meta_resolver: MetaReaderResolver,
366    meta_string_resolver: MetaStringReaderResolver,
367    pub ref_reader: RefReader,
368    current_depth: u32,
369}
370
371// Safety: ReadContext follows the same invariants as WriteContext—external orchestrators ensure
372// single-threaded use. Concurrent access to the same instance across threads is forbidden and
373// would result in undefined behavior. With exclusive use guaranteed, the Send/Sync markers are safe
374// even though Rc is used internally.
375#[allow(clippy::needless_lifetimes)]
376unsafe impl<'a> Send for ReadContext<'a> {}
377#[allow(clippy::needless_lifetimes)]
378unsafe impl<'a> Sync for ReadContext<'a> {}
379
380impl<'a> ReadContext<'a> {
381    pub fn new(type_resolver: TypeResolver, config: Config) -> ReadContext<'a> {
382        ReadContext {
383            type_resolver,
384            config: config.clone(),
385            compatible: config.compatible,
386            share_meta: config.share_meta,
387            xlang: config.xlang,
388            max_dyn_depth: config.max_dyn_depth,
389            check_struct_version: config.check_struct_version,
390            check_string_read: config.check_string_read,
391            reader: Reader::default(),
392            meta_resolver: MetaReaderResolver::default(),
393            meta_string_resolver: MetaStringReaderResolver::default(),
394            ref_reader: RefReader::new(),
395            current_depth: 0,
396        }
397    }
398
399    /// Get type resolver
400    #[inline(always)]
401    pub fn get_type_resolver(&self) -> &TypeResolver {
402        &self.type_resolver
403    }
404
405    /// Check if compatible mode is enabled
406    #[inline(always)]
407    pub fn is_compatible(&self) -> bool {
408        self.compatible
409    }
410
411    /// Check if meta sharing is enabled
412    #[inline(always)]
413    pub fn is_share_meta(&self) -> bool {
414        self.share_meta
415    }
416
417    /// Check if xlang mode is enabled
418    #[inline(always)]
419    pub fn is_xlang(&self) -> bool {
420        self.xlang
421    }
422
423    /// Check if class version checking is enabled
424    #[inline(always)]
425    pub fn is_check_struct_version(&self) -> bool {
426        self.check_struct_version
427    }
428
429    /// Check if UTF-8 string payload validation is enabled.
430    #[inline(always)]
431    pub fn is_check_string_read(&self) -> bool {
432        self.check_string_read
433    }
434
435    /// Get maximum dynamic depth
436    #[inline(always)]
437    pub fn max_dyn_depth(&self) -> u32 {
438        self.max_dyn_depth
439    }
440
441    #[inline(always)]
442    pub fn attach_reader(&mut self, reader: Reader<'a>) {
443        self.reader = reader;
444    }
445
446    #[inline(always)]
447    pub fn detach_reader(&mut self) -> Reader<'_> {
448        mem::take(&mut self.reader)
449    }
450
451    #[inline(always)]
452    pub fn get_type_info_by_index(&self, type_index: usize) -> Result<&Rc<TypeInfo>, Error> {
453        self.meta_resolver.get(type_index).ok_or_else(|| {
454            Error::type_error(format!("TypeInfo not found for type index: {}", type_index))
455        })
456    }
457
458    #[inline(always)]
459    pub fn get_meta(&self, type_index: usize) -> Result<&Rc<TypeInfo>, Error> {
460        self.get_type_info_by_index(type_index)
461    }
462
463    /// Read type meta inline using streaming protocol.
464    /// Returns the TypeInfo for this type.
465    #[inline(always)]
466    pub fn read_type_meta(&mut self) -> Result<Rc<TypeInfo>, Error> {
467        self.meta_resolver
468            .read_type_meta(&mut self.reader, &self.type_resolver, &self.config)
469    }
470
471    pub fn read_any_type_info(&mut self) -> Result<Rc<TypeInfo>, Error> {
472        let fory_type_id = self.reader.read_u8()? as u32;
473        // should be compiled to jump table generation
474        match fory_type_id {
475            types::ENUM | types::STRUCT | types::EXT | types::TYPED_UNION => {
476                let user_type_id = self.reader.read_var_u32()?;
477                self.type_resolver
478                    .get_user_type_info_by_id(user_type_id)
479                    .ok_or_else(|| Error::type_error("ID harness not found"))
480            }
481            types::COMPATIBLE_STRUCT | types::NAMED_COMPATIBLE_STRUCT => {
482                // Read type meta inline using streaming protocol
483                self.read_type_meta()
484            }
485            types::NAMED_ENUM | types::NAMED_EXT | types::NAMED_STRUCT | types::NAMED_UNION => {
486                if self.is_share_meta() {
487                    // Read type meta inline using streaming protocol
488                    self.read_type_meta()
489                } else {
490                    let namespace = self.read_meta_string()?.to_owned();
491                    let type_name = self.read_meta_string()?.to_owned();
492                    let rc_namespace = Rc::from(namespace.clone());
493                    let rc_type_name = Rc::from(type_name.clone());
494                    self.type_resolver
495                        .get_type_info_by_meta_string_name(rc_namespace, rc_type_name)
496                        .or_else(|| {
497                            self.type_resolver.get_type_info_by_name(
498                                namespace.original.as_str(),
499                                type_name.original.as_str(),
500                            )
501                        })
502                        .ok_or_else(|| {
503                            Error::type_error(format!(
504                                "Name harness not found: namespace='{}', type='{}'",
505                                namespace.original, type_name.original
506                            ))
507                        })
508                }
509            }
510            _ => self
511                .type_resolver
512                .get_type_info_by_id(fory_type_id)
513                .ok_or_else(|| Error::type_error("ID harness not found")),
514        }
515    }
516
517    #[inline(always)]
518    pub fn get_type_info(&self, type_id: &std::any::TypeId) -> Result<Rc<TypeInfo>, Error> {
519        self.type_resolver.get_type_info(type_id)
520    }
521
522    #[inline(always)]
523    pub fn read_meta_string(&mut self) -> Result<&MetaString, Error> {
524        self.meta_string_resolver.read_meta_string(&mut self.reader)
525    }
526
527    #[inline(always)]
528    pub fn inc_depth(&mut self) -> Result<(), Error> {
529        self.current_depth += 1;
530        if self.current_depth > self.max_dyn_depth() {
531            return Err(Error::depth_exceed(format!(
532                "Maximum dynamic object nesting depth ({}) exceeded. Current depth: {}. \
533                    This may indicate a circular reference or overly deep object graph. \
534                    Consider increasing max_dyn_depth if this is expected.",
535                self.max_dyn_depth(),
536                self.current_depth
537            )));
538        }
539        Ok(())
540    }
541
542    #[inline(always)]
543    pub fn dec_depth(&mut self) {
544        self.current_depth = self.current_depth.saturating_sub(1);
545    }
546
547    #[inline(always)]
548    pub fn reset(&mut self) {
549        self.meta_resolver.reset();
550        self.meta_string_resolver.reset();
551        self.ref_reader.reset();
552        self.current_depth = 0;
553    }
554}
fory_core/context.rs

fory_core/
context.rs
