orphan.h (17758B)
1 // Copyright (c) 2013-2014 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 22 #pragma once 23 24 #include "layout.h" 25 26 CAPNP_BEGIN_HEADER 27 28 namespace capnp { 29 30 class StructSchema; 31 class ListSchema; 32 struct DynamicStruct; 33 struct DynamicList; 34 namespace _ { struct OrphanageInternal; } 35 36 template <typename T> 37 class Orphan { 38 // Represents an object which is allocated within some message builder but has no pointers 39 // pointing at it. An Orphan can later be "adopted" by some other object as one of that object's 40 // fields, without having to copy the orphan. For a field `foo` of pointer type, the generated 41 // code will define builder methods `void adoptFoo(Orphan<T>)` and `Orphan<T> disownFoo()`. 42 // Orphans can also be created independently of any parent using an Orphanage. 43 // 44 // `Orphan<T>` can be moved but not copied, like `Own<T>`, so that it is impossible for one 45 // orphan to be adopted multiple times. If an orphan is destroyed without being adopted, its 46 // contents are zero'd out (and possibly reused, if we ever implement the ability to reuse space 47 // in a message arena). 48 49 public: 50 Orphan() = default; 51 KJ_DISALLOW_COPY(Orphan); 52 Orphan(Orphan&&) = default; 53 Orphan& operator=(Orphan&&) = default; 54 inline Orphan(_::OrphanBuilder&& builder): builder(kj::mv(builder)) {} 55 56 inline BuilderFor<T> get(); 57 // Get the underlying builder. If the orphan is null, this will allocate and return a default 58 // object rather than crash. This is done for security -- otherwise, you might enable a DoS 59 // attack any time you disown a field and fail to check if it is null. In the case of structs, 60 // this means that the orphan is no longer null after get() returns. In the case of lists, 61 // no actual object is allocated since a simple empty ListBuilder can be returned. 62 63 inline ReaderFor<T> getReader() const; 64 65 inline bool operator==(decltype(nullptr)) const { return builder == nullptr; } 66 inline bool operator!=(decltype(nullptr)) const { return builder != nullptr; } 67 68 inline void truncate(uint size); 69 // Resize an object (which must be a list or a blob) to the given size. 70 // 71 // If the new size is less than the original, the remaining elements will be discarded. The 72 // list is never moved in this case. If the list happens to be located at the end of its segment 73 // (which is always true if the list was the last thing allocated), the removed memory will be 74 // reclaimed (reducing the messag size), otherwise it is simply zeroed. The reclaiming behavior 75 // is particularly useful for allocating buffer space when you aren't sure how much space you 76 // actually need: you can pre-allocate, say, a 4k byte array, read() from a file into it, and 77 // then truncate it back to the amount of space actually used. 78 // 79 // If the new size is greater than the original, the list is extended with default values. If 80 // the list is the last object in its segment *and* there is enough space left in the segment to 81 // extend it to cover the new values, then the list is extended in-place. Otherwise, it must be 82 // moved to a new location, leaving a zero'd hole in the previous space that won't be filled. 83 // This copy is shallow; sub-objects will simply be reparented, not copied. 84 // 85 // Any existing readers or builders pointing at the object are invalidated by this call (even if 86 // it doesn't move). You must call `get()` or `getReader()` again to get the new, valid pointer. 87 88 private: 89 _::OrphanBuilder builder; 90 91 template <typename, Kind> 92 friend struct _::PointerHelpers; 93 template <typename, Kind> 94 friend struct List; 95 template <typename U> 96 friend class Orphan; 97 friend class Orphanage; 98 friend class MessageBuilder; 99 }; 100 101 class Orphanage: private kj::DisallowConstCopy { 102 // Use to directly allocate Orphan objects, without having a parent object allocate and then 103 // disown the object. 104 105 public: 106 inline Orphanage(): arena(nullptr) {} 107 108 template <typename BuilderType> 109 static Orphanage getForMessageContaining(BuilderType builder); 110 // Construct an Orphanage that allocates within the message containing the given Builder. This 111 // allows the constructed Orphans to be adopted by objects within said message. 112 // 113 // This constructor takes the builder rather than having the builder have a getOrphanage() method 114 // because this is an advanced feature and we don't want to pollute the builder APIs with it. 115 // 116 // Note that if you have a direct pointer to the `MessageBuilder`, you can simply call its 117 // `getOrphanage()` method. 118 119 template <typename RootType> 120 Orphan<RootType> newOrphan() const; 121 // Allocate a new orphaned struct. 122 123 template <typename RootType> 124 Orphan<RootType> newOrphan(uint size) const; 125 // Allocate a new orphaned list or blob. 126 127 Orphan<DynamicStruct> newOrphan(StructSchema schema) const; 128 // Dynamically create an orphan struct with the given schema. You must 129 // #include <capnp/dynamic.h> to use this. 130 131 Orphan<DynamicList> newOrphan(ListSchema schema, uint size) const; 132 // Dynamically create an orphan list with the given schema. You must #include <capnp/dynamic.h> 133 // to use this. 134 135 template <typename Reader> 136 Orphan<FromReader<Reader>> newOrphanCopy(Reader copyFrom) const; 137 // Allocate a new orphaned object (struct, list, or blob) and initialize it as a copy of the 138 // given object. 139 140 template <typename T> 141 Orphan<List<ListElementType<FromReader<T>>>> newOrphanConcat(kj::ArrayPtr<T> lists) const; 142 template <typename T> 143 Orphan<List<ListElementType<FromReader<T>>>> newOrphanConcat(kj::ArrayPtr<const T> lists) const; 144 // Given an array of List readers, copy and concatenate the lists, creating a new Orphan. 145 // 146 // Note that compared to allocating the list yourself and using `setWithCaveats()` to set each 147 // item, this method avoids the "caveats": the new list will be allocated with the element size 148 // being the maximum of that from all the input lists. This is particularly important when 149 // concatenating struct lists: if the lists were created using a newer version of the protocol 150 // in which some new fields had been added to the struct, using `setWithCaveats()` would 151 // truncate off those new fields. 152 153 Orphan<Data> referenceExternalData(Data::Reader data) const; 154 // Creates an Orphan<Data> that points at an existing region of memory (e.g. from another message) 155 // without copying it. There are some SEVERE restrictions on how this can be used: 156 // - The memory must remain valid until the `MessageBuilder` is destroyed (even if the orphan is 157 // abandoned). 158 // - Because the data is const, you will not be allowed to obtain a `Data::Builder` 159 // for this blob. Any call which would return such a builder will throw an exception. You 160 // can, however, obtain a Reader, e.g. via orphan.getReader() or from a parent Reader (once 161 // the orphan is adopted). It is your responsibility to make sure your code can deal with 162 // these problems when using this optimization; if you can't, allocate a copy instead. 163 // - `data.begin()` must be aligned to a machine word boundary (32-bit or 64-bit depending on 164 // the CPU). Any pointer returned by malloc() as well as any data blob obtained from another 165 // Cap'n Proto message satisfies this. 166 // - If `data.size()` is not a multiple of 8, extra bytes past data.end() up until the next 8-byte 167 // boundary will be visible in the raw message when it is written out. Thus, there must be no 168 // secrets in these bytes. Data blobs obtained from other Cap'n Proto messages should be safe 169 // as these bytes should be zero (unless the sender had the same problem). 170 // 171 // The array will actually become one of the message's segments. The data can thus be adopted 172 // into the message tree without copying it. This is particularly useful when referencing very 173 // large blobs, such as whole mmap'd files. 174 175 private: 176 _::BuilderArena* arena; 177 _::CapTableBuilder* capTable; 178 179 inline explicit Orphanage(_::BuilderArena* arena, _::CapTableBuilder* capTable) 180 : arena(arena), capTable(capTable) {} 181 182 template <typename T, Kind = CAPNP_KIND(T)> 183 struct GetInnerBuilder; 184 template <typename T, Kind = CAPNP_KIND(T)> 185 struct GetInnerReader; 186 template <typename T> 187 struct NewOrphanListImpl; 188 189 friend class MessageBuilder; 190 friend struct _::OrphanageInternal; 191 }; 192 193 // ======================================================================================= 194 // Inline implementation details. 195 196 namespace _ { // private 197 198 template <typename T, Kind = CAPNP_KIND(T)> 199 struct OrphanGetImpl; 200 201 template <typename T> 202 struct OrphanGetImpl<T, Kind::PRIMITIVE> { 203 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 204 builder.truncate(size, _::elementSizeForType<T>()); 205 } 206 }; 207 208 template <typename T> 209 struct OrphanGetImpl<T, Kind::STRUCT> { 210 static inline typename T::Builder apply(_::OrphanBuilder& builder) { 211 return typename T::Builder(builder.asStruct(_::structSize<T>())); 212 } 213 static inline typename T::Reader applyReader(const _::OrphanBuilder& builder) { 214 return typename T::Reader(builder.asStructReader(_::structSize<T>())); 215 } 216 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 217 builder.truncate(size, _::structSize<T>()); 218 } 219 }; 220 221 #if !CAPNP_LITE 222 template <typename T> 223 struct OrphanGetImpl<T, Kind::INTERFACE> { 224 static inline typename T::Client apply(_::OrphanBuilder& builder) { 225 return typename T::Client(builder.asCapability()); 226 } 227 static inline typename T::Client applyReader(const _::OrphanBuilder& builder) { 228 return typename T::Client(builder.asCapability()); 229 } 230 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 231 builder.truncate(size, ElementSize::POINTER); 232 } 233 }; 234 #endif // !CAPNP_LITE 235 236 template <typename T, Kind k> 237 struct OrphanGetImpl<List<T, k>, Kind::LIST> { 238 static inline typename List<T>::Builder apply(_::OrphanBuilder& builder) { 239 return typename List<T>::Builder(builder.asList(_::ElementSizeForType<T>::value)); 240 } 241 static inline typename List<T>::Reader applyReader(const _::OrphanBuilder& builder) { 242 return typename List<T>::Reader(builder.asListReader(_::ElementSizeForType<T>::value)); 243 } 244 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 245 builder.truncate(size, ElementSize::POINTER); 246 } 247 }; 248 249 template <typename T> 250 struct OrphanGetImpl<List<T, Kind::STRUCT>, Kind::LIST> { 251 static inline typename List<T>::Builder apply(_::OrphanBuilder& builder) { 252 return typename List<T>::Builder(builder.asStructList(_::structSize<T>())); 253 } 254 static inline typename List<T>::Reader applyReader(const _::OrphanBuilder& builder) { 255 return typename List<T>::Reader(builder.asListReader(_::ElementSizeForType<T>::value)); 256 } 257 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 258 builder.truncate(size, ElementSize::POINTER); 259 } 260 }; 261 262 template <> 263 struct OrphanGetImpl<Text, Kind::BLOB> { 264 static inline Text::Builder apply(_::OrphanBuilder& builder) { 265 return Text::Builder(builder.asText()); 266 } 267 static inline Text::Reader applyReader(const _::OrphanBuilder& builder) { 268 return Text::Reader(builder.asTextReader()); 269 } 270 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 271 builder.truncate(size, ElementSize::POINTER); 272 } 273 }; 274 275 template <> 276 struct OrphanGetImpl<Data, Kind::BLOB> { 277 static inline Data::Builder apply(_::OrphanBuilder& builder) { 278 return Data::Builder(builder.asData()); 279 } 280 static inline Data::Reader applyReader(const _::OrphanBuilder& builder) { 281 return Data::Reader(builder.asDataReader()); 282 } 283 static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) { 284 builder.truncate(size, ElementSize::POINTER); 285 } 286 }; 287 288 struct OrphanageInternal { 289 static inline _::BuilderArena* getArena(Orphanage orphanage) { return orphanage.arena; } 290 static inline _::CapTableBuilder* getCapTable(Orphanage orphanage) { return orphanage.capTable; } 291 }; 292 293 } // namespace _ (private) 294 295 template <typename T> 296 inline BuilderFor<T> Orphan<T>::get() { 297 return _::OrphanGetImpl<T>::apply(builder); 298 } 299 300 template <typename T> 301 inline ReaderFor<T> Orphan<T>::getReader() const { 302 return _::OrphanGetImpl<T>::applyReader(builder); 303 } 304 305 template <typename T> 306 inline void Orphan<T>::truncate(uint size) { 307 _::OrphanGetImpl<ListElementType<T>>::truncateListOf(builder, bounded(size) * ELEMENTS); 308 } 309 310 template <> 311 inline void Orphan<Text>::truncate(uint size) { 312 builder.truncateText(bounded(size) * ELEMENTS); 313 } 314 315 template <> 316 inline void Orphan<Data>::truncate(uint size) { 317 builder.truncate(bounded(size) * ELEMENTS, ElementSize::BYTE); 318 } 319 320 template <typename T> 321 struct Orphanage::GetInnerBuilder<T, Kind::STRUCT> { 322 static inline _::StructBuilder apply(typename T::Builder& t) { 323 return t._builder; 324 } 325 }; 326 327 template <typename T> 328 struct Orphanage::GetInnerBuilder<T, Kind::LIST> { 329 static inline _::ListBuilder apply(typename T::Builder& t) { 330 return t.builder; 331 } 332 }; 333 334 template <typename BuilderType> 335 Orphanage Orphanage::getForMessageContaining(BuilderType builder) { 336 auto inner = GetInnerBuilder<FromBuilder<BuilderType>>::apply(builder); 337 return Orphanage(inner.getArena(), inner.getCapTable()); 338 } 339 340 template <typename RootType> 341 Orphan<RootType> Orphanage::newOrphan() const { 342 return Orphan<RootType>(_::OrphanBuilder::initStruct(arena, capTable, _::structSize<RootType>())); 343 } 344 345 template <typename T, Kind k> 346 struct Orphanage::NewOrphanListImpl<List<T, k>> { 347 static inline _::OrphanBuilder apply( 348 _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) { 349 return _::OrphanBuilder::initList( 350 arena, capTable, bounded(size) * ELEMENTS, _::ElementSizeForType<T>::value); 351 } 352 }; 353 354 template <typename T> 355 struct Orphanage::NewOrphanListImpl<List<T, Kind::STRUCT>> { 356 static inline _::OrphanBuilder apply( 357 _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) { 358 return _::OrphanBuilder::initStructList( 359 arena, capTable, bounded(size) * ELEMENTS, _::structSize<T>()); 360 } 361 }; 362 363 template <> 364 struct Orphanage::NewOrphanListImpl<Text> { 365 static inline _::OrphanBuilder apply( 366 _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) { 367 return _::OrphanBuilder::initText(arena, capTable, bounded(size) * BYTES); 368 } 369 }; 370 371 template <> 372 struct Orphanage::NewOrphanListImpl<Data> { 373 static inline _::OrphanBuilder apply( 374 _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) { 375 return _::OrphanBuilder::initData(arena, capTable, bounded(size) * BYTES); 376 } 377 }; 378 379 template <typename RootType> 380 Orphan<RootType> Orphanage::newOrphan(uint size) const { 381 return Orphan<RootType>(NewOrphanListImpl<RootType>::apply(arena, capTable, size)); 382 } 383 384 template <typename T> 385 struct Orphanage::GetInnerReader<T, Kind::STRUCT> { 386 static inline _::StructReader apply(const typename T::Reader& t) { 387 return t._reader; 388 } 389 }; 390 391 template <typename T> 392 struct Orphanage::GetInnerReader<T, Kind::LIST> { 393 static inline _::ListReader apply(const typename T::Reader& t) { 394 return t.reader; 395 } 396 }; 397 398 template <typename T> 399 struct Orphanage::GetInnerReader<T, Kind::BLOB> { 400 static inline const typename T::Reader& apply(const typename T::Reader& t) { 401 return t; 402 } 403 }; 404 405 template <typename Reader> 406 inline Orphan<FromReader<Reader>> Orphanage::newOrphanCopy(Reader copyFrom) const { 407 return Orphan<FromReader<Reader>>(_::OrphanBuilder::copy( 408 arena, capTable, GetInnerReader<FromReader<Reader>>::apply(copyFrom))); 409 } 410 411 template <typename T> 412 inline Orphan<List<ListElementType<FromReader<T>>>> 413 Orphanage::newOrphanConcat(kj::ArrayPtr<T> lists) const { 414 return newOrphanConcat(kj::implicitCast<kj::ArrayPtr<const T>>(lists)); 415 } 416 template <typename T> 417 inline Orphan<List<ListElementType<FromReader<T>>>> 418 Orphanage::newOrphanConcat(kj::ArrayPtr<const T> lists) const { 419 // Optimization / simplification: Rely on List<T>::Reader containing nothing except a 420 // _::ListReader. 421 static_assert(sizeof(T) == sizeof(_::ListReader), "lists are not bare readers?"); 422 kj::ArrayPtr<const _::ListReader> raw( 423 reinterpret_cast<const _::ListReader*>(lists.begin()), lists.size()); 424 typedef ListElementType<FromReader<T>> Element; 425 return Orphan<List<Element>>( 426 _::OrphanBuilder::concat(arena, capTable, 427 _::elementSizeForType<Element>(), 428 _::minStructSizeForElement<Element>(), raw)); 429 } 430 431 inline Orphan<Data> Orphanage::referenceExternalData(Data::Reader data) const { 432 return Orphan<Data>(_::OrphanBuilder::referenceExternalData(arena, data)); 433 } 434 435 } // namespace capnp 436 437 CAPNP_END_HEADER