qubit_codec/value/
value_codec_registration.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8
9//! Registration type definitions are colocated with their public module.
10
11use crate::ValueCodecId;
12use crate::ValueCodecRegistrationSource;
13
14/// One statically linked value-codec implementation.
15///
16/// A registration bundles the stable identifier used for lookup and duplicate
17/// detection, a borrowed executable descriptor, and the link-time location the
18/// registration was declared at. It is produced by
19/// [`register_value_string_codec!`](crate::register_value_string_codec) or
20/// [`register_value_bytes_codec!`](crate::register_value_bytes_codec)
21/// rather than built by hand. Applications may also construct a registration
22/// manually from static data and pass it to a local
23/// [`ValueCodecRegistry`](crate::ValueCodecRegistry).
24///
25/// The ID has already been validated by [`ValueCodecId`]. The descriptor must
26/// live in static storage because registrations borrow it with a `'static`
27/// lifetime. The source records where the registration came from for duplicate
28/// ID diagnostics; it does not affect those static requirements.
29///
30/// The registration macros validate codecs through the matching descriptor.
31/// Encoder and decoder error types must implement `Error + Send + Sync +
32/// 'static`; codec and value types do not need those bounds.
33///
34/// Registration macros create these values from codec descriptors and submit
35/// them to the process-wide inventory. See
36/// [`register_value_string_codec!`](crate::register_value_string_codec) and
37/// [`register_value_bytes_codec!`](crate::register_value_bytes_codec) for
38/// executable registration examples. For a local registry, this type can be
39/// constructed directly from a validated ID, a static descriptor, and source
40/// information as shown below.
41/// # Type Parameters
42///
43/// - `D`: Static descriptor type that executes the registered codec.
44///
45/// # Examples
46///
47/// ```
48/// use qubit_codec::ValueCodecId;
49/// use qubit_codec::ValueCodecRegistration;
50/// use qubit_codec::ValueCodecRegistrationSource;
51///
52/// static DESCRIPTOR: u8 = 1;
53/// let registration = ValueCodecRegistration::new(
54///     ValueCodecId::new("example.u8"),
55///     &DESCRIPTOR,
56///     ValueCodecRegistrationSource::new("qubit-codec", "example", "src/example.rs", 1),
57/// );
58/// assert_eq!(registration.id().as_str(), "example.u8");
59/// assert_eq!(*registration.descriptor(), 1);
60/// ```
61#[derive(Clone, Copy, Debug)]
62pub struct ValueCodecRegistration<D: 'static> {
63    /// Stable identifier used by registry lookups and duplicate detection.
64    id: ValueCodecId,
65    /// Executable descriptor borrowed from static storage for the registration
66    /// lifetime.
67    descriptor: &'static D,
68    /// Link-time location identifying where the registration macro was invoked.
69    source: ValueCodecRegistrationSource,
70}
71impl<D: 'static> ValueCodecRegistration<D> {
72    /// Creates a registration from the validated facts captured by a
73    /// registration macro.
74    ///
75    /// Use the registration macros to submit a codec to the process-wide
76    /// inventory. For a local registry, construct this value from static data
77    /// and pass a reference to
78    /// [`ValueCodecRegistry::from_registrations`](crate::ValueCodecRegistry::from_registrations).
79    /// The ID must already be validated, and the descriptor must have static
80    /// storage. The source provides location details for duplicate-ID
81    /// diagnostics.
82    ///
83    /// # Parameters
84    ///
85    /// - `id`: Stable identifier used for registry lookup and duplicate
86    ///   detection.
87    /// - `descriptor`: Descriptor in static storage that performs codec
88    ///   operations.
89    /// - `source`: Declaration location captured by the registration macro.
90    ///
91    /// # Returns
92    ///
93    /// A copyable registration borrowing the static descriptor.
94    #[inline]
95    #[must_use]
96    pub const fn new(id: ValueCodecId, descriptor: &'static D, source: ValueCodecRegistrationSource) -> Self {
97        Self { id, descriptor, source }
98    }
99
100    /// Returns the stable value-codec ID used by registry lookups.
101    ///
102    /// # Returns
103    ///
104    /// The registration's validated, copyable identifier.
105    #[inline]
106    #[must_use]
107    pub const fn id(&self) -> ValueCodecId {
108        self.id
109    }
110
111    /// Returns the descriptor used to execute this codec.
112    ///
113    /// # Returns
114    ///
115    /// A static borrow of the descriptor associated with this registration.
116    #[inline]
117    #[must_use = "the codec descriptor is needed to perform codec operations"]
118    pub const fn descriptor(&self) -> &'static D {
119        self.descriptor
120    }
121
122    /// Returns the source location captured at the registration declaration.
123    ///
124    /// # Returns
125    ///
126    /// The copyable package, module, file, and line information for this
127    /// registration.
128    #[inline]
129    #[must_use]
130    pub const fn source(&self) -> ValueCodecRegistrationSource {
131        self.source
132    }
133}
qubit_codec/value/value_codec_registration.rs

qubit_codec/value/
value_codec_registration.rs
