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    pub(crate) remaining_unbacked_container_items: usize,
385
386    // Context-specific fields
387    pub reader: Reader<'a>,
388    pub meta_resolver: MetaReaderResolver,
389    meta_string_resolver: MetaStringReaderResolver,
390    pub ref_reader: RefReader,
391    current_depth: u32,
392}
393
394// Safety: ReadContext follows the same invariants as WriteContext—external orchestrators ensure
395// single-threaded use. Concurrent access to the same instance across threads is forbidden and
396// would result in undefined behavior. With exclusive use guaranteed, the Send/Sync markers are safe
397// even though Rc is used internally.
398#[allow(clippy::needless_lifetimes)]
399unsafe impl<'a> Send for ReadContext<'a> {}
400#[allow(clippy::needless_lifetimes)]
401unsafe impl<'a> Sync for ReadContext<'a> {}
402
403impl<'a> ReadContext<'a> {
404    pub fn new(type_resolver: TypeResolver, config: Config) -> ReadContext<'a> {
405        ReadContext {
406            type_resolver,
407            config: config.clone(),
408            compatible: config.compatible,
409            share_meta: config.share_meta,
410            xlang: config.xlang,
411            max_dyn_depth: config.max_dyn_depth,
412            check_struct_version: config.check_struct_version,
413            check_string_read: config.check_string_read,
414            remaining_graph_memory_bytes: 0,
415            remaining_unbacked_container_items: 0,
416            reader: Reader::default(),
417            meta_resolver: MetaReaderResolver::default(),
418            meta_string_resolver: MetaStringReaderResolver::default(),
419            ref_reader: RefReader::new(),
420            current_depth: 0,
421        }
422    }
423
424    /// Get type resolver
425    #[inline(always)]
426    pub fn get_type_resolver(&self) -> &TypeResolver {
427        &self.type_resolver
428    }
429
430    /// Check if compatible mode is enabled
431    #[inline(always)]
432    pub fn is_compatible(&self) -> bool {
433        self.compatible
434    }
435
436    /// Check if meta sharing is enabled
437    #[inline(always)]
438    pub fn is_share_meta(&self) -> bool {
439        self.share_meta
440    }
441
442    /// Check if xlang mode is enabled
443    #[inline(always)]
444    pub fn is_xlang(&self) -> bool {
445        self.xlang
446    }
447
448    /// Check if class version checking is enabled
449    #[inline(always)]
450    pub fn is_check_struct_version(&self) -> bool {
451        self.check_struct_version
452    }
453
454    /// Check if UTF-8 string payload validation is enabled.
455    #[inline(always)]
456    pub fn is_check_string_read(&self) -> bool {
457        self.check_string_read
458    }
459
460    /// Get maximum dynamic depth
461    #[inline(always)]
462    pub fn max_dyn_depth(&self) -> u32 {
463        self.max_dyn_depth
464    }
465
466    #[inline(always)]
467    pub fn attach_reader(&mut self, reader: Reader<'a>) {
468        self.reader = reader;
469    }
470
471    #[inline(always)]
472    #[doc(hidden)]
473    pub fn reserve_graph_memory(&mut self, bytes: usize) -> Result<(), Error> {
474        let remaining = self.remaining_graph_memory_bytes;
475        if bytes > remaining {
476            return Err(graph_memory_exceeded(
477                bytes,
478                remaining,
479                self.config.max_graph_memory_bytes,
480            ));
481        }
482        self.remaining_graph_memory_bytes = remaining - bytes;
483        Ok(())
484    }
485
486    #[inline(always)]
487    #[doc(hidden)]
488    pub fn remaining_unbacked_container_items(&self) -> usize {
489        self.remaining_unbacked_container_items
490    }
491
492    #[inline(always)]
493    #[doc(hidden)]
494    pub fn reserve_unbacked_container_items(&mut self, items: usize) -> Result<(), Error> {
495        let remaining = self.remaining_unbacked_container_items;
496        if items > remaining {
497            return Err(unbacked_container_items_exceeded(items, remaining));
498        }
499        self.remaining_unbacked_container_items = remaining - items;
500        Ok(())
501    }
502
503    #[inline(always)]
504    pub fn detach_reader(&mut self) -> Reader<'_> {
505        mem::take(&mut self.reader)
506    }
507
508    #[inline(always)]
509    pub fn get_type_info_by_index(&self, type_index: usize) -> Result<&Rc<TypeInfo>, Error> {
510        self.meta_resolver.get(type_index).ok_or_else(|| {
511            Error::type_error(format!("TypeInfo not found for type index: {}", type_index))
512        })
513    }
514
515    #[inline(always)]
516    pub fn get_meta(&self, type_index: usize) -> Result<&Rc<TypeInfo>, Error> {
517        self.get_type_info_by_index(type_index)
518    }
519
520    /// Read type meta inline using streaming protocol.
521    /// Returns the TypeInfo for this type.
522    #[inline(always)]
523    pub fn read_type_meta(&mut self) -> Result<Rc<TypeInfo>, Error> {
524        self.meta_resolver
525            .read_type_meta(&mut self.reader, &self.type_resolver, &self.config)
526    }
527
528    pub fn read_any_type_info(&mut self) -> Result<Rc<TypeInfo>, Error> {
529        let fory_type_id = self.reader.read_u8()? as u32;
530        // should be compiled to jump table generation
531        match fory_type_id {
532            types::ENUM | types::STRUCT | types::EXT | types::TYPED_UNION => {
533                let user_type_id = self.reader.read_var_u32()?;
534                self.type_resolver
535                    .get_user_type_info_by_id(user_type_id)
536                    .ok_or_else(|| Error::type_error("ID harness not found"))
537            }
538            types::COMPATIBLE_STRUCT | types::NAMED_COMPATIBLE_STRUCT => {
539                // Read type meta inline using streaming protocol
540                self.read_type_meta()
541            }
542            types::NAMED_ENUM | types::NAMED_EXT | types::NAMED_STRUCT | types::NAMED_UNION => {
543                if self.is_share_meta() {
544                    // Read type meta inline using streaming protocol
545                    self.read_type_meta()
546                } else {
547                    self.read_named_type_info()
548                }
549            }
550            _ => self
551                .type_resolver
552                .get_type_info_by_id(fory_type_id)
553                .ok_or_else(|| Error::type_error("ID harness not found")),
554        }
555    }
556
557    // Name decoding and resolver fallback allocate; keep them out of the common ID and compatible
558    // dispatch body without marking successful named dispatch as cold.
559    #[inline(never)]
560    fn read_named_type_info(&mut self) -> Result<Rc<TypeInfo>, Error> {
561        let namespace = self.read_meta_string()?.to_owned();
562        let type_name = self.read_meta_string()?.to_owned();
563        let rc_namespace = Rc::from(namespace.clone());
564        let rc_type_name = Rc::from(type_name.clone());
565        self.type_resolver
566            .get_type_info_by_meta_string_name(rc_namespace, rc_type_name)
567            .or_else(|| {
568                self.type_resolver
569                    .get_type_info_by_name(namespace.original.as_str(), type_name.original.as_str())
570            })
571            .ok_or_else(|| {
572                Error::type_error(format!(
573                    "Name harness not found: namespace='{}', type='{}'",
574                    namespace.original, type_name.original
575                ))
576            })
577    }
578
579    #[inline(always)]
580    pub fn get_provider_type_info(
581        &self,
582        provider_type_id: &std::any::TypeId,
583    ) -> Result<Rc<TypeInfo>, Error> {
584        self.type_resolver.get_provider_type_info(provider_type_id)
585    }
586
587    #[inline(always)]
588    pub fn get_target_type_info(
589        &self,
590        target_type_id: &std::any::TypeId,
591    ) -> Result<Rc<TypeInfo>, Error> {
592        self.type_resolver.get_target_type_info(target_type_id)
593    }
594
595    #[inline(always)]
596    pub fn read_meta_string(&mut self) -> Result<&MetaString, Error> {
597        self.meta_string_resolver.read_meta_string(&mut self.reader)
598    }
599
600    #[inline(always)]
601    pub fn inc_depth(&mut self) -> Result<(), Error> {
602        self.current_depth += 1;
603        if self.current_depth > self.max_dyn_depth() {
604            return Err(Error::depth_exceed(format!(
605                "Maximum dynamic object nesting depth ({}) exceeded. Current depth: {}. \
606                    This may indicate a circular reference or overly deep object graph. \
607                    Consider increasing max_dyn_depth if this is expected.",
608                self.max_dyn_depth(),
609                self.current_depth
610            )));
611        }
612        Ok(())
613    }
614
615    #[inline(always)]
616    pub fn dec_depth(&mut self) {
617        // Nested readers decrement only after their child completed successfully. An error keeps
618        // the failed path's depth until the root reset owns all read-side cleanup.
619        self.current_depth = self.current_depth.saturating_sub(1);
620    }
621
622    #[inline(always)]
623    pub fn reset(&mut self) {
624        self.meta_resolver.reset();
625        self.meta_string_resolver.reset();
626        self.ref_reader.reset();
627        // Root reset is the only failure-cleanup owner for read depth.
628        self.current_depth = 0;
629        self.remaining_unbacked_container_items = 0;
630    }
631}
632
633#[cold]
634#[inline(never)]
635fn graph_memory_exceeded(bytes: usize, remaining: usize, limit: usize) -> Error {
636    Error::invalid_data(format!(
637        "estimated graph memory request {} bytes exceeds max_graph_memory_bytes remaining budget {} bytes out of effective limit {} bytes",
638        bytes, remaining, limit
639    ))
640}
641
642#[cold]
643#[inline(never)]
644fn unbacked_container_items_exceeded(items: usize, remaining: usize) -> Error {
645    Error::invalid_data(format!(
646        "container read work request {items} items exceeds max_unbacked_container_items remaining budget {remaining} items"
647    ))
648}
fory_core/context.rs

fory_core/
context.rs
