1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2024 Google LLC. All rights reserved. 3 // 4 // Use of this source code is governed by a BSD-style 5 // license that can be found in the LICENSE file or at 6 // https://developers.google.com/open-source/licenses/bsd 7 8 //! Traits that are implemented by codegen types. 9 10 use crate::__internal::SealedInternal; 11 use crate::{MutProxied, MutProxy, ViewProxy}; 12 use create::Parse; 13 use interop::{MessageMutInterop, MessageViewInterop, OwnedMessageInterop}; 14 use read::Serialize; 15 use std::fmt::Debug; 16 use write::{Clear, ClearAndParse, MergeFrom}; 17 18 /// A trait that all generated owned message types implement. 19 pub trait Message: SealedInternal 20 + MutProxied 21 // Create traits: 22 + Parse + Default 23 // Read traits: 24 + Debug + Serialize 25 // Write traits: 26 + Clear + ClearAndParse + MergeFrom 27 // Thread safety: 28 + Send + Sync 29 // Copy/Clone: 30 + Clone 31 // C++ Interop: 32 + OwnedMessageInterop 33 { 34 } 35 36 /// A trait that all generated message views implement. 37 pub trait MessageView<'msg>: SealedInternal 38 + ViewProxy<'msg, Proxied = Self::Message> 39 // Read traits: 40 + Debug + Serialize + Default 41 // Thread safety: 42 + Send + Sync 43 // Copy/Clone: 44 + Copy + Clone 45 // C++ Interop: 46 + MessageViewInterop<'msg> 47 { 48 #[doc(hidden)] 49 type Message: Message; 50 } 51 52 /// A trait that all generated message muts implement. 53 pub trait MessageMut<'msg>: SealedInternal 54 + MutProxy<'msg, MutProxied = Self::Message> 55 // Read traits: 56 + Debug + Serialize 57 // Write traits: 58 // TODO: MsgMut should impl ClearAndParse. 59 + Clear + MergeFrom 60 // Thread safety: 61 + Sync 62 // Copy/Clone: 63 // (Neither) 64 // C++ Interop: 65 + MessageMutInterop<'msg> 66 { 67 #[doc(hidden)] 68 type Message: Message; 69 } 70 71 /// Operations related to constructing a message. Only owned messages implement 72 /// these traits. 73 pub(crate) mod create { 74 use super::SealedInternal; 75 pub trait Parse: SealedInternal + Sized { parse(serialized: &[u8]) -> Result<Self, crate::ParseError>76 fn parse(serialized: &[u8]) -> Result<Self, crate::ParseError>; 77 } 78 } 79 80 /// Operations related to reading some aspect of a message (methods that would 81 /// have a `&self` receiver on an owned message). Owned messages, views, and 82 /// muts all implement these traits. 83 pub(crate) mod read { 84 use super::SealedInternal; 85 86 pub trait Serialize: SealedInternal { serialize(&self) -> Result<Vec<u8>, crate::SerializeError>87 fn serialize(&self) -> Result<Vec<u8>, crate::SerializeError>; 88 } 89 } 90 91 /// Operations related to mutating a message (methods that would have a `&mut 92 /// self` receiver on an owned message). Owned messages and muts implement these 93 /// traits. 94 pub(crate) mod write { 95 use super::SealedInternal; 96 use crate::AsView; 97 98 pub trait Clear: SealedInternal { clear(&mut self)99 fn clear(&mut self); 100 } 101 102 pub trait ClearAndParse: SealedInternal { clear_and_parse(&mut self, data: &[u8]) -> Result<(), crate::ParseError>103 fn clear_and_parse(&mut self, data: &[u8]) -> Result<(), crate::ParseError>; 104 } 105 106 pub trait MergeFrom: AsView + SealedInternal { merge_from(&mut self, src: impl AsView<Proxied = Self::Proxied>)107 fn merge_from(&mut self, src: impl AsView<Proxied = Self::Proxied>); 108 } 109 } 110 111 /// Traits related to interop with C or C++. 112 /// 113 /// These traits are deliberately not available on the prelude, as they should 114 /// be used rarely and with great care. 115 pub(crate) mod interop { 116 use super::SealedInternal; 117 use std::ffi::c_void; 118 119 /// Traits related to owned message interop. Note that these trait fns 120 /// are only available on C++ kernel as upb interop of owned messages 121 /// requires more work to handle the Arena behavior. 122 pub trait OwnedMessageInterop: SealedInternal { 123 /// Drops `self` and returns an underlying pointer that it was wrapping 124 /// without deleting it. 125 /// 126 /// The caller is responsible for ensuring the returned pointer is 127 /// subsequently deleted (eg by moving it into a std::unique_ptr in 128 /// C++), or else it will leak. 129 #[cfg(cpp_kernel)] __unstable_leak_raw_message(self) -> *mut c_void130 fn __unstable_leak_raw_message(self) -> *mut c_void; 131 132 /// Takes exclusive ownership of the `raw_message`. 133 /// 134 /// # Safety 135 /// - The underlying message must be for the same type as `Self` 136 /// - The pointer passed in must not be used by the caller after being 137 /// passed here (must not be read, written, or deleted) 138 #[cfg(cpp_kernel)] __unstable_take_ownership_of_raw_message(raw_message: *mut c_void) -> Self139 unsafe fn __unstable_take_ownership_of_raw_message(raw_message: *mut c_void) -> Self; 140 } 141 142 /// Traits related to message view interop. 143 pub trait MessageViewInterop<'msg>: SealedInternal { 144 /// Borrows `self` as an underlying C++ raw pointer. 145 /// 146 /// Note that the returned Value must be used under the same constraints 147 /// as though it were a borrow of `self`: it should be treated as a 148 /// `const Message*` in C++, and not be mutated in any way, and any 149 /// mutation to the parent message may invalidate it, and it 150 /// must not be deleted. __unstable_as_raw_message(&self) -> *const c_void151 fn __unstable_as_raw_message(&self) -> *const c_void; 152 153 /// Wraps the provided pointer as a MessageView. 154 /// 155 /// This takes a ref of a pointer so that a stack variable's lifetime 156 /// can be used for a safe lifetime; under most cases this is 157 /// the correct lifetime and this should be used as: 158 /// ``` 159 /// fn called_from_cpp(msg: *const c_void) { 160 /// // `msg` is known live for the current stack frame, so view's 161 /// // lifetime is also tied to the current stack frame here: 162 /// let view = unsafe { __unstable_wrap_raw_message(&msg); } 163 /// do_something_with_view(view); 164 /// } 165 /// ``` 166 /// 167 /// # Safety 168 /// - The underlying message must be for the same type as `Self` 169 /// - The underlying message must be alive for 'msg and not mutated 170 /// while the wrapper is live. __unstable_wrap_raw_message(raw: &'msg *const c_void) -> Self171 unsafe fn __unstable_wrap_raw_message(raw: &'msg *const c_void) -> Self; 172 173 /// Wraps the provided pointer as a MessageView. 174 /// 175 /// Unlike `__unstable_wrap_raw_message` this has no constraints 176 /// on lifetime: the caller has a free choice for the lifetime. 177 /// 178 /// As this is much easier to get the lifetime wrong than 179 /// `__unstable_wrap_raw_message`, prefer using that wherever 180 /// your lifetime can be tied to a stack lifetime, and only use this one 181 /// if its not possible (e.g. with a 'static lifetime). 182 /// 183 /// # Safety 184 /// - The underlying message must be for the same type as `Self` 185 /// - The underlying message must be alive for the caller-chosen 'msg 186 /// and not mutated while the wrapper is live. __unstable_wrap_raw_message_unchecked_lifetime(raw: *const c_void) -> Self187 unsafe fn __unstable_wrap_raw_message_unchecked_lifetime(raw: *const c_void) -> Self; 188 } 189 190 /// Traits related to message mut interop. Note that these trait fns 191 /// are only available on C++ kernel as upb interop of owned messages 192 /// requires more work to handle the Arena behavior. 193 pub trait MessageMutInterop<'msg>: SealedInternal { 194 /// Exclusive borrows `self` as an underlying mutable C++ raw pointer. 195 /// 196 /// Note that the returned Value must be used under the same constraints 197 /// as though it were a mut borrow of `self`: it should be treated as a 198 /// non-owned `Message*` in C++. And any mutation to the parent message 199 /// may invalidate it, and it must not be deleted. 200 #[cfg(cpp_kernel)] __unstable_as_raw_message_mut(&mut self) -> *mut c_void201 fn __unstable_as_raw_message_mut(&mut self) -> *mut c_void; 202 203 /// Wraps the provided C++ pointer as a MessageMut. 204 /// 205 /// This takes a ref of a pointer so that a stack variable's lifetime 206 /// can be used for a safe lifetime; under most cases this is 207 /// the correct lifetime and this should be used as: 208 /// ``` 209 /// fn called_from_cpp(msg: *mut c_void) { 210 /// // `msg` is known live for the current stack frame, so mut's 211 /// // lifetime is also tied to the current stack frame here: 212 /// let m = unsafe { __unstable_wrap_raw_message_mut(&mut msg); } 213 /// do_something_with_mut(m); 214 /// } 215 /// 216 /// # Safety 217 /// - The underlying message must be for the same type as `Self` 218 /// - The underlying message must be alive for 'msg and not read or 219 /// mutated while the wrapper is live. 220 #[cfg(cpp_kernel)] __unstable_wrap_raw_message_mut(raw: &'msg mut *mut c_void) -> Self221 unsafe fn __unstable_wrap_raw_message_mut(raw: &'msg mut *mut c_void) -> Self; 222 223 /// Wraps the provided pointer as a MessageMut. 224 /// 225 /// Unlike `__unstable_wrap_raw_message_mut` this has no constraints 226 /// on lifetime: the caller has a free choice for the lifetime. 227 /// 228 /// As this is much easier to get the lifetime wrong than 229 /// `__unstable_wrap_raw_message_mut`, prefer using that wherever 230 /// the lifetime can be tied to a stack lifetime, and only use this one 231 /// if its not possible (e.g. with a 'static lifetime). 232 /// 233 /// # Safety 234 /// - The underlying message must be for the same type as `Self` 235 /// - The underlying message must be alive for the caller-chosen 'msg 236 /// and not mutated while the wrapper is live. 237 #[cfg(cpp_kernel)] __unstable_wrap_raw_message_mut_unchecked_lifetime(raw: *mut c_void) -> Self238 unsafe fn __unstable_wrap_raw_message_mut_unchecked_lifetime(raw: *mut c_void) -> Self; 239 } 240 } 241