capnp/
traits.rs

1// Copyright (c) 2013-2015 Sandstorm Development Group, Inc. and contributors
2// Licensed under the MIT License:
3//
4// Permission is hereby granted, free of charge, to any person obtaining a copy
5// of this software and associated documentation files (the "Software"), to deal
6// in the Software without restriction, including without limitation the rights
7// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8// copies of the Software, and to permit persons to whom the Software is
9// furnished to do so, subject to the following conditions:
10//
11// The above copyright notice and this permission notice shall be included in
12// all copies or substantial portions of the Software.
13//
14// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20// THE SOFTWARE.
21
22use crate::private::layout::CapTable;
23use crate::private::layout::{
24    ListReader, PointerBuilder, PointerReader, StructBuilder, StructReader, StructSize,
25};
26use crate::Result;
27
28use core::marker::PhantomData;
29
30pub trait HasStructSize {
31    const STRUCT_SIZE: StructSize;
32}
33
34/// Trait for all types that can be converted to a low-level `StructReader`.
35pub trait IntoInternalStructReader<'a> {
36    fn into_internal_struct_reader(self) -> StructReader<'a>;
37}
38
39/// Trait for all types that can be converted to a low-level `ListReader`.
40pub trait IntoInternalListReader<'a> {
41    fn into_internal_list_reader(self) -> ListReader<'a>;
42}
43
44pub trait FromPointerReader<'a>: Sized {
45    fn get_from_pointer(
46        reader: &PointerReader<'a>,
47        default: Option<&'a [crate::Word]>,
48    ) -> Result<Self>;
49}
50
51/// A trait to encode relationships between readers and builders.
52///
53/// If `Foo` is a Cap'n Proto struct and `Bar` is a Rust-native struct, then
54/// `foo::Reader<'a>` is to `foo::Owned` as `&'a Bar` is to `Bar`, and
55/// `foo::Builder<'a>` is to `foo::Owned` as `&'a mut Bar` is to `Bar`.
56/// The relationship is formalized by an `impl capnp::traits::Owned for foo::Owned`.
57/// Because Cap'n Proto struct layout differs from Rust struct layout, a `foo::Owned` value
58/// cannot be used for anything interesting on its own; the `foo::Owned` type is useful
59/// nonetheless as a type parameter, e.g. for a generic container that owns a Cap'n Proto
60/// message of type `T: capnp::traits::Owned`.
61pub trait Owned: crate::introspect::Introspect {
62    type Reader<'a>: FromPointerReader<'a> + SetterInput<Self>;
63    type Builder<'a>: FromPointerBuilder<'a>;
64}
65
66pub trait OwnedStruct: crate::introspect::Introspect {
67    type Reader<'a>: From<StructReader<'a>> + SetterInput<Self> + IntoInternalStructReader<'a>;
68    type Builder<'a>: From<StructBuilder<'a>> + HasStructSize;
69}
70
71pub trait Pipelined {
72    type Pipeline;
73}
74
75pub trait FromPointerBuilder<'a>: Sized {
76    fn init_pointer(builder: PointerBuilder<'a>, length: u32) -> Self;
77    fn get_from_pointer(
78        builder: PointerBuilder<'a>,
79        default: Option<&'a [crate::Word]>,
80    ) -> Result<Self>;
81}
82
83/// A trait marking types that can be passed as inputs to setter methods.
84/// `Receiver` is intended to be an `Owned`, representing the destination type.
85///
86/// This trait allows setters to support multiple types of input. For example,
87/// a text field setter accepts values of type `&str` and of type `text::Reader`.
88pub trait SetterInput<Receiver: ?Sized> {
89    /// Copies the values from `input` into `builder`, where `builder`
90    /// represents the backing memory of a `<Receiver as Owned>::Builder`.
91    ///
92    /// End user code should never need to call this method directly.
93    fn set_pointer_builder(
94        builder: PointerBuilder<'_>,
95        input: Self,
96        canonicalize: bool,
97    ) -> Result<()>;
98}
99
100/// A trait for types that can be "imbued" with capabilities.
101///
102/// A newly-read message from the network might contain capability pointers
103/// but until the message has been imbued with the actual capabilities,
104/// those pointers will not be usable.
105pub trait Imbue<'a> {
106    fn imbue(&mut self, caps: &'a CapTable);
107}
108
109/// Like `Imbue`, but the capability table is mutable.
110pub trait ImbueMut<'a> {
111    fn imbue_mut(&mut self, caps: &'a mut CapTable);
112}
113
114/// User-defined Cap'n Proto structs and interfaces are statically assigned a
115/// 64-bit type ID. This trait allows the ID to be retrieved.
116pub trait HasTypeId {
117    const TYPE_ID: u64;
118}
119
120pub trait IndexMove<I, T> {
121    fn index_move(&self, index: I) -> T;
122}
123
124pub struct ListIter<T, U> {
125    marker: PhantomData<U>,
126    list: T,
127    index: u32,
128    size: u32,
129}
130
131impl<T, U> ListIter<T, U> {
132    pub fn new(list: T, size: u32) -> Self {
133        Self {
134            list,
135            index: 0,
136            size,
137            marker: PhantomData,
138        }
139    }
140}
141
142impl<U, T: IndexMove<u32, U>> ::core::iter::Iterator for ListIter<T, U> {
143    type Item = U;
144    fn next(&mut self) -> ::core::option::Option<U> {
145        if self.index < self.size {
146            let result = self.list.index_move(self.index);
147            self.index += 1;
148            Some(result)
149        } else {
150            None
151        }
152    }
153
154    fn size_hint(&self) -> (usize, Option<usize>) {
155        let remaining = self.size as usize - self.index as usize;
156        (remaining, Some(remaining))
157    }
158
159    fn nth(&mut self, p: usize) -> Option<U> {
160        let Some(p) = p.try_into().ok() else {
161            self.index = self.size;
162            return None;
163        };
164        let Some(nth_index) = self.index.checked_add(p) else {
165            self.index = self.size;
166            return None;
167        };
168        if nth_index < self.size {
169            self.index = nth_index;
170            let result = self.list.index_move(self.index);
171            self.index += 1;
172            Some(result)
173        } else {
174            self.index = self.size;
175            None
176        }
177    }
178}
179
180impl<U, T: IndexMove<u32, U>> ::core::iter::ExactSizeIterator for ListIter<T, U> {
181    fn len(&self) -> usize {
182        self.size as usize - self.index as usize
183    }
184}
185
186impl<U, T: IndexMove<u32, U>> ::core::iter::DoubleEndedIterator for ListIter<T, U> {
187    fn next_back(&mut self) -> ::core::option::Option<U> {
188        if self.size > self.index {
189            self.size -= 1;
190            Some(self.list.index_move(self.size))
191        } else {
192            None
193        }
194    }
195}
196
197/// Iterator for a list whose indices are of type `u16`.
198pub struct ShortListIter<T, U> {
199    marker: PhantomData<U>,
200    list: T,
201    index: u16,
202    size: u16,
203}
204
205impl<T, U> ShortListIter<T, U> {
206    pub fn new(list: T, size: u16) -> Self {
207        Self {
208            list,
209            index: 0,
210            size,
211            marker: PhantomData,
212        }
213    }
214}
215
216impl<U, T: IndexMove<u16, U>> ::core::iter::Iterator for ShortListIter<T, U> {
217    type Item = U;
218    fn next(&mut self) -> ::core::option::Option<U> {
219        if self.index < self.size {
220            let result = self.list.index_move(self.index);
221            self.index += 1;
222            Some(result)
223        } else {
224            None
225        }
226    }
227
228    fn size_hint(&self) -> (usize, Option<usize>) {
229        let remaining = self.size as usize - self.index as usize;
230        (remaining, Some(remaining))
231    }
232
233    fn nth(&mut self, p: usize) -> Option<U> {
234        let Some(p) = p.try_into().ok() else {
235            self.index = self.size;
236            return None;
237        };
238        let Some(nth_index) = self.index.checked_add(p) else {
239            self.index = self.size;
240            return None;
241        };
242        if nth_index < self.size {
243            self.index = nth_index;
244            let result = self.list.index_move(self.index);
245            self.index += 1;
246            Some(result)
247        } else {
248            self.index = self.size;
249            None
250        }
251    }
252}
253
254impl<U, T: IndexMove<u16, U>> ::core::iter::ExactSizeIterator for ShortListIter<T, U> {
255    fn len(&self) -> usize {
256        self.size as usize - self.index as usize
257    }
258}
259
260impl<U, T: IndexMove<u16, U>> ::core::iter::DoubleEndedIterator for ShortListIter<T, U> {
261    fn next_back(&mut self) -> ::core::option::Option<U> {
262        if self.size > self.index {
263            self.size -= 1;
264            Some(self.list.index_move(self.size))
265        } else {
266            None
267        }
268    }
269}
capnp/traits.rs

capnp/
traits.rs
