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_provider_type_info(
179        &self,
180        provider_type_id: &std::any::TypeId,
181    ) -> Result<Rc<TypeInfo>, Error> {
182        self.type_resolver.get_provider_type_info(provider_type_id)
183    }
184
185    #[inline(always)]
186    pub fn get_target_type_info(
187        &self,
188        target_type_id: &std::any::TypeId,
189    ) -> Result<Rc<TypeInfo>, Error> {
190        self.type_resolver.get_target_type_info(target_type_id)
191    }
192
193    /// Check if compatible mode is enabled
194    #[inline(always)]
195    pub fn is_compatible(&self) -> bool {
196        self.compatible
197    }
198
199    /// Check if meta sharing is enabled
200    #[inline(always)]
201    pub fn is_share_meta(&self) -> bool {
202        self.share_meta
203    }
204
205    /// Check if string compression is enabled
206    #[inline(always)]
207    pub fn is_compress_string(&self) -> bool {
208        self.compress_string
209    }
210
211    /// Check if xlang mode is enabled
212    #[inline(always)]
213    pub fn is_xlang(&self) -> bool {
214        self.xlang
215    }
216
217    /// Check if class version checking is enabled
218    #[inline(always)]
219    pub fn is_check_struct_version(&self) -> bool {
220        self.check_struct_version
221    }
222
223    /// Check if reference tracking is enabled
224    #[inline(always)]
225    pub fn is_track_ref(&self) -> bool {
226        self.track_ref
227    }
228
229    /// Write type meta inline using streaming protocol.
230    /// Writes index marker with LSB indicating new type or reference.
231    #[inline(always)]
232    pub fn write_type_meta(&mut self, type_id: std::any::TypeId) -> Result<(), Error> {
233        self.meta_resolver
234            .write_type_meta(&mut self.writer, type_id, &self.type_resolver)
235    }
236
237    /// Write generated struct type info without Rust TypeId hash lookups.
238    #[inline(always)]
239    pub fn write_struct_type_info<T: StructSerializer>(&mut self) -> Result<(), Error> {
240        let rust_type_id = std::any::TypeId::of::<T>();
241        let type_index = T::type_index();
242        let type_id = self.type_resolver.get_type_id_by_index(type_index)?;
243        match type_id {
244            TypeId::STRUCT | TypeId::ENUM | TypeId::EXT | TypeId::TYPED_UNION => {
245                self.writer.write_u8(type_id as u8);
246                let user_type_id = self
247                    .type_resolver
248                    .get_user_type_id_by_index(&rust_type_id, type_index)?;
249                self.writer.write_var_u32(user_type_id);
250            }
251            TypeId::COMPATIBLE_STRUCT | TypeId::NAMED_COMPATIBLE_STRUCT => {
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            TypeId::NAMED_ENUM | TypeId::NAMED_EXT | TypeId::NAMED_STRUCT | TypeId::NAMED_UNION
261                if self.is_share_meta() =>
262            {
263                self.writer.write_u8(type_id as u8);
264                self.meta_resolver.write_type_meta_fast(
265                    &mut self.writer,
266                    rust_type_id,
267                    type_index,
268                    &self.type_resolver,
269                )?;
270            }
271            _ => {
272                self.write_provider_type_info(type_id as u32, rust_type_id)?;
273            }
274        }
275        Ok(())
276    }
277
278    pub fn write_provider_type_info(
279        &mut self,
280        wire_type_id: u32,
281        provider_type_id: std::any::TypeId,
282    ) -> Result<Rc<TypeInfo>, Error> {
283        let type_info = self
284            .type_resolver
285            .get_provider_type_info(&provider_type_id)?;
286        self.write_resolved_type_info(wire_type_id, type_info)
287    }
288
289    pub fn write_target_type_info(
290        &mut self,
291        wire_type_id: u32,
292        target_type_id: std::any::TypeId,
293    ) -> Result<Rc<TypeInfo>, Error> {
294        let type_info = self.type_resolver.get_target_type_info(&target_type_id)?;
295        self.write_resolved_type_info(wire_type_id, type_info)
296    }
297
298    #[doc(hidden)]
299    #[inline(always)]
300    pub fn write_resolved_type_info(
301        &mut self,
302        wire_type_id: u32,
303        type_info: Rc<TypeInfo>,
304    ) -> Result<Rc<TypeInfo>, Error> {
305        if types::is_internal_type(wire_type_id) {
306            self.writer.write_u8(wire_type_id as u8);
307            return Ok(type_info);
308        }
309        let wire_type_id = type_info.get_type_id();
310        let namespace = type_info.get_namespace();
311        let type_name = type_info.get_type_name();
312        self.writer.write_u8(wire_type_id as u8);
313        // should be compiled to jump table generation
314        match wire_type_id {
315            TypeId::ENUM | TypeId::STRUCT | TypeId::EXT | TypeId::TYPED_UNION => {
316                let user_type_id = type_info.get_user_type_id();
317                self.writer.write_var_u32(user_type_id);
318            }
319            TypeId::COMPATIBLE_STRUCT | TypeId::NAMED_COMPATIBLE_STRUCT => {
320                self.meta_resolver
321                    .write_resolved_type_meta(&mut self.writer, &type_info)?;
322            }
323            TypeId::NAMED_ENUM | TypeId::NAMED_EXT | TypeId::NAMED_STRUCT | TypeId::NAMED_UNION => {
324                if self.is_share_meta() {
325                    self.meta_resolver
326                        .write_resolved_type_meta(&mut self.writer, &type_info)?;
327                } else {
328                    self.write_meta_string_bytes(namespace)?;
329                    self.write_meta_string_bytes(type_name)?;
330                }
331            }
332            _ => {
333                // default case: do nothing
334            }
335        }
336        Ok(type_info)
337    }
338
339    #[inline(always)]
340    pub fn write_meta_string_bytes(&mut self, ms: Rc<MetaString>) -> Result<(), Error> {
341        self.meta_string_resolver
342            .write_meta_string_bytes(&mut self.writer, ms)
343    }
344
345    #[inline(always)]
346    pub fn reset(&mut self) {
347        self.meta_resolver.reset();
348        self.meta_string_resolver.reset();
349        self.ref_writer.reset();
350    }
351}
352
353#[allow(clippy::needless_lifetimes)]
354impl<'a> Drop for WriteContext<'a> {
355    fn drop(&mut self) {
356        unsafe {
357            drop(Box::from_raw(self.writer.bf));
358        }
359    }
360}
361
362// Safety: WriteContext is only shared across threads via higher-level pooling code that
363// ensures single-threaded access while the context is in use. Users must never hold the same
364// instance on multiple threads simultaneously; that would violate the invariants and result in
365// undefined behavior. Under that assumption, marking it Send/Sync is sound.
366#[allow(clippy::needless_lifetimes)]
367unsafe impl<'a> Send for WriteContext<'a> {}
368#[allow(clippy::needless_lifetimes)]
369unsafe impl<'a> Sync for WriteContext<'a> {}
370
371/// Deserialization state container used on a single thread at a time.
372/// Sharing the same instance across threads simultaneously causes undefined behavior.
373pub struct ReadContext<'a> {
374    // Replicated environment fields (direct access, no Arc indirection for flags)
375    type_resolver: TypeResolver,
376    config: Config,
377    compatible: bool,
378    share_meta: bool,
379    xlang: bool,
380    max_dyn_depth: u32,
381    check_struct_version: bool,
382    check_string_read: bool,
383    pub(crate) remaining_graph_memory_bytes: usize,
384
385    // Context-specific fields
386    pub reader: Reader<'a>,
387    pub meta_resolver: MetaReaderResolver,
388    meta_string_resolver: MetaStringReaderResolver,
389    pub ref_reader: RefReader,
390    current_depth: u32,
391}
392
393// Safety: ReadContext follows the same invariants as WriteContext—external orchestrators ensure
394// single-threaded use. Concurrent access to the same instance across threads is forbidden and
395// would result in undefined behavior. With exclusive use guaranteed, the Send/Sync markers are safe
396// even though Rc is used internally.
397#[allow(clippy::needless_lifetimes)]
398unsafe impl<'a> Send for ReadContext<'a> {}
399#[allow(clippy::needless_lifetimes)]
400unsafe impl<'a> Sync for ReadContext<'a> {}
401
402impl<'a> ReadContext<'a> {
403    pub fn new(type_resolver: TypeResolver, config: Config) -> ReadContext<'a> {
404        ReadContext {
405            type_resolver,
406            config: config.clone(),
407            compatible: config.compatible,
408            share_meta: config.share_meta,
409            xlang: config.xlang,
410            max_dyn_depth: config.max_dyn_depth,
411            check_struct_version: config.check_struct_version,
412            check_string_read: config.check_string_read,
413            remaining_graph_memory_bytes: 0,
414            reader: Reader::default(),
415            meta_resolver: MetaReaderResolver::default(),
416            meta_string_resolver: MetaStringReaderResolver::default(),
417            ref_reader: RefReader::new(),
418            current_depth: 0,
419        }
420    }
421
422    /// Get type resolver
423    #[inline(always)]
424    pub fn get_type_resolver(&self) -> &TypeResolver {
425        &self.type_resolver
426    }
427
428    /// Check if compatible mode is enabled
429    #[inline(always)]
430    pub fn is_compatible(&self) -> bool {
431        self.compatible
432    }
433
434    /// Check if meta sharing is enabled
435    #[inline(always)]
436    pub fn is_share_meta(&self) -> bool {
437        self.share_meta
438    }
439
440    /// Check if xlang mode is enabled
441    #[inline(always)]
442    pub fn is_xlang(&self) -> bool {
443        self.xlang
444    }
445
446    /// Check if class version checking is enabled
447    #[inline(always)]
448    pub fn is_check_struct_version(&self) -> bool {
449        self.check_struct_version
450    }
451
452    /// Check if UTF-8 string payload validation is enabled.
453    #[inline(always)]
454    pub fn is_check_string_read(&self) -> bool {
455        self.check_string_read
456    }
457
458    /// Get maximum dynamic depth
459    #[inline(always)]
460    pub fn max_dyn_depth(&self) -> u32 {
461        self.max_dyn_depth
462    }
463
464    #[inline(always)]
465    pub fn attach_reader(&mut self, reader: Reader<'a>) {
466        self.reader = reader;
467    }
468
469    #[inline(always)]
470    #[doc(hidden)]
471    pub fn reserve_graph_memory(&mut self, bytes: usize) -> Result<(), Error> {
472        let remaining = self.remaining_graph_memory_bytes;
473        if bytes > remaining {
474            return Err(graph_memory_exceeded(
475                bytes,
476                remaining,
477                self.config.max_graph_memory_bytes,
478            ));
479        }
480        self.remaining_graph_memory_bytes = remaining - bytes;
481        Ok(())
482    }
483
484    #[inline(always)]
485    pub fn detach_reader(&mut self) -> Reader<'_> {
486        mem::take(&mut self.reader)
487    }
488
489    #[inline(always)]
490    pub fn get_type_info_by_index(&self, type_index: usize) -> Result<&Rc<TypeInfo>, Error> {
491        self.meta_resolver.get(type_index).ok_or_else(|| {
492            Error::type_error(format!("TypeInfo not found for type index: {}", type_index))
493        })
494    }
495
496    #[inline(always)]
497    pub fn get_meta(&self, type_index: usize) -> Result<&Rc<TypeInfo>, Error> {
498        self.get_type_info_by_index(type_index)
499    }
500
501    /// Read type meta inline using streaming protocol.
502    /// Returns the TypeInfo for this type.
503    #[inline(always)]
504    pub fn read_type_meta(&mut self) -> Result<Rc<TypeInfo>, Error> {
505        self.meta_resolver
506            .read_type_meta(&mut self.reader, &self.type_resolver, &self.config)
507    }
508
509    pub fn read_any_type_info(&mut self) -> Result<Rc<TypeInfo>, Error> {
510        let fory_type_id = self.reader.read_u8()? as u32;
511        // should be compiled to jump table generation
512        match fory_type_id {
513            types::ENUM | types::STRUCT | types::EXT | types::TYPED_UNION => {
514                let user_type_id = self.reader.read_var_u32()?;
515                self.type_resolver
516                    .get_user_type_info_by_id(user_type_id)
517                    .ok_or_else(|| Error::type_error("ID harness not found"))
518            }
519            types::COMPATIBLE_STRUCT | types::NAMED_COMPATIBLE_STRUCT => {
520                // Read type meta inline using streaming protocol
521                self.read_type_meta()
522            }
523            types::NAMED_ENUM | types::NAMED_EXT | types::NAMED_STRUCT | types::NAMED_UNION => {
524                if self.is_share_meta() {
525                    // Read type meta inline using streaming protocol
526                    self.read_type_meta()
527                } else {
528                    let namespace = self.read_meta_string()?.to_owned();
529                    let type_name = self.read_meta_string()?.to_owned();
530                    let rc_namespace = Rc::from(namespace.clone());
531                    let rc_type_name = Rc::from(type_name.clone());
532                    self.type_resolver
533                        .get_type_info_by_meta_string_name(rc_namespace, rc_type_name)
534                        .or_else(|| {
535                            self.type_resolver.get_type_info_by_name(
536                                namespace.original.as_str(),
537                                type_name.original.as_str(),
538                            )
539                        })
540                        .ok_or_else(|| {
541                            Error::type_error(format!(
542                                "Name harness not found: namespace='{}', type='{}'",
543                                namespace.original, type_name.original
544                            ))
545                        })
546                }
547            }
548            _ => self
549                .type_resolver
550                .get_type_info_by_id(fory_type_id)
551                .ok_or_else(|| Error::type_error("ID harness not found")),
552        }
553    }
554
555    #[inline(always)]
556    pub fn get_provider_type_info(
557        &self,
558        provider_type_id: &std::any::TypeId,
559    ) -> Result<Rc<TypeInfo>, Error> {
560        self.type_resolver.get_provider_type_info(provider_type_id)
561    }
562
563    #[inline(always)]
564    pub fn get_target_type_info(
565        &self,
566        target_type_id: &std::any::TypeId,
567    ) -> Result<Rc<TypeInfo>, Error> {
568        self.type_resolver.get_target_type_info(target_type_id)
569    }
570
571    #[inline(always)]
572    pub fn read_meta_string(&mut self) -> Result<&MetaString, Error> {
573        self.meta_string_resolver.read_meta_string(&mut self.reader)
574    }
575
576    #[inline(always)]
577    pub fn inc_depth(&mut self) -> Result<(), Error> {
578        self.current_depth += 1;
579        if self.current_depth > self.max_dyn_depth() {
580            return Err(Error::depth_exceed(format!(
581                "Maximum dynamic object nesting depth ({}) exceeded. Current depth: {}. \
582                    This may indicate a circular reference or overly deep object graph. \
583                    Consider increasing max_dyn_depth if this is expected.",
584                self.max_dyn_depth(),
585                self.current_depth
586            )));
587        }
588        Ok(())
589    }
590
591    #[inline(always)]
592    pub fn dec_depth(&mut self) {
593        self.current_depth = self.current_depth.saturating_sub(1);
594    }
595
596    #[inline(always)]
597    pub fn reset(&mut self) {
598        self.meta_resolver.reset();
599        self.meta_string_resolver.reset();
600        self.ref_reader.reset();
601        self.current_depth = 0;
602    }
603}
604
605#[cold]
606#[inline(never)]
607fn graph_memory_exceeded(bytes: usize, remaining: usize, limit: usize) -> Error {
608    Error::invalid_data(format!(
609        "estimated graph memory request {} bytes exceeds max_graph_memory_bytes remaining budget {} bytes out of effective limit {} bytes",
610        bytes, remaining, limit
611    ))
612}
fory_core/context.rs

fory_core/
context.rs
