orphan.h 17.3 KB
Newer Older
Kenton Varda's avatar
Kenton Varda committed
1 2
// Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
// Licensed under the MIT License:
3
//
Kenton Varda's avatar
Kenton Varda committed
4 5 6 7 8 9
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
10
//
Kenton Varda's avatar
Kenton Varda committed
11 12
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
13
//
Kenton Varda's avatar
Kenton Varda committed
14 15 16 17 18 19 20
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
21

22
#pragma once
23 24 25

#include "layout.h"

26 27
CAPNP_BEGIN_HEADER

28 29 30 31 32 33
namespace capnp {

class StructSchema;
class ListSchema;
struct DynamicStruct;
struct DynamicList;
34
namespace _ { struct OrphanageInternal; }
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53

template <typename T>
class Orphan {
  // Represents an object which is allocated within some message builder but has no pointers
  // pointing at it.  An Orphan can later be "adopted" by some other object as one of that object's
  // fields, without having to copy the orphan.  For a field `foo` of pointer type, the generated
  // code will define builder methods `void adoptFoo(Orphan<T>)` and `Orphan<T> disownFoo()`.
  // Orphans can also be created independently of any parent using an Orphanage.
  //
  // `Orphan<T>` can be moved but not copied, like `Own<T>`, so that it is impossible for one
  // orphan to be adopted multiple times.  If an orphan is destroyed without being adopted, its
  // contents are zero'd out (and possibly reused, if we ever implement the ability to reuse space
  // in a message arena).

public:
  Orphan() = default;
  KJ_DISALLOW_COPY(Orphan);
  Orphan(Orphan&&) = default;
  Orphan& operator=(Orphan&&) = default;
54
  inline Orphan(_::OrphanBuilder&& builder): builder(kj::mv(builder)) {}
55

56
  inline BuilderFor<T> get();
57 58 59 60 61 62
  // Get the underlying builder.  If the orphan is null, this will allocate and return a default
  // object rather than crash.  This is done for security -- otherwise, you might enable a DoS
  // attack any time you disown a field and fail to check if it is null.  In the case of structs,
  // this means that the orphan is no longer null after get() returns.  In the case of lists,
  // no actual object is allocated since a simple empty ListBuilder can be returned.

63
  inline ReaderFor<T> getReader() const;
64

65 66
  inline bool operator==(decltype(nullptr)) const { return builder == nullptr; }
  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 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
  // If the new size is less than the original, the remaining elements will be discarded. The
  // list is never moved in this case. If the list happens to be located at the end of its segment
  // (which is always true if the list was the last thing allocated), the removed memory will be
  // reclaimed (reducing the messag size), otherwise it is simply zeroed. The reclaiming behavior
  // is particularly useful for allocating buffer space when you aren't sure how much space you
  // actually need: you can pre-allocate, say, a 4k byte array, read() from a file into it, and
  // then truncate it back to the amount of space actually used.
  //
  // If the new size is greater than the original, the list is extended with default values. If
  // the list is the last object in its segment *and* there is enough space left in the segment to
  // extend it to cover the new values, then the list is extended in-place. Otherwise, it must be
  // moved to a new location, leaving a zero'd hole in the previous space that won't be filled.
  // This copy is shallow; sub-objects will simply be reparented, not copied.
  //
  // Any existing readers or builders pointing at the object are invalidated by this call (even if
  // it doesn't move). You must call `get()` or `getReader()` again to get the new, valid pointer.
87

88 89 90 91 92 93 94
private:
  _::OrphanBuilder builder;

  template <typename, Kind>
  friend struct _::PointerHelpers;
  template <typename, Kind>
  friend struct List;
95 96
  template <typename U>
  friend class Orphan;
97
  friend class Orphanage;
98
  friend class MessageBuilder;
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
};

class Orphanage: private kj::DisallowConstCopy {
  // Use to directly allocate Orphan objects, without having a parent object allocate and then
  // disown the object.

public:
  inline Orphanage(): arena(nullptr) {}

  template <typename BuilderType>
  static Orphanage getForMessageContaining(BuilderType builder);
  // Construct an Orphanage that allocates within the message containing the given Builder.  This
  // allows the constructed Orphans to be adopted by objects within said message.
  //
  // This constructor takes the builder rather than having the builder have a getOrphanage() method
  // because this is an advanced feature and we don't want to pollute the builder APIs with it.
  //
  // Note that if you have a direct pointer to the `MessageBuilder`, you can simply call its
  // `getOrphanage()` method.

  template <typename RootType>
120
  Orphan<RootType> newOrphan() const;
121 122 123
  // Allocate a new orphaned struct.

  template <typename RootType>
124
  Orphan<RootType> newOrphan(uint size) const;
125 126
  // Allocate a new orphaned list or blob.

127
  Orphan<DynamicStruct> newOrphan(StructSchema schema) const;
128 129 130
  // Dynamically create an orphan struct with the given schema.  You must
  // #include <capnp/dynamic.h> to use this.

131
  Orphan<DynamicList> newOrphan(ListSchema schema, uint size) const;
132 133 134 135
  // Dynamically create an orphan list with the given schema.  You must #include <capnp/dynamic.h>
  // to use this.

  template <typename Reader>
136
  Orphan<FromReader<Reader>> newOrphanCopy(Reader copyFrom) const;
137 138 139
  // Allocate a new orphaned object (struct, list, or blob) and initialize it as a copy of the
  // given object.

140 141 142 143 144 145 146 147 148 149 150 151 152
  template <typename T>
  Orphan<List<ListElementType<FromReader<T>>>> newOrphanConcat(kj::ArrayPtr<T> lists) const;
  template <typename T>
  Orphan<List<ListElementType<FromReader<T>>>> newOrphanConcat(kj::ArrayPtr<const T> lists) const;
  // Given an array of List readers, copy and concatenate the lists, creating a new Orphan.
  //
  // Note that compared to allocating the list yourself and using `setWithCaveats()` to set each
  // item, this method avoids the "caveats": the new list will be allocated with the element size
  // being the maximum of that from all the input lists. This is particularly important when
  // concatenating struct lists: if the lists were created using a newer version of the protocol
  // in which some new fields had been added to the struct, using `setWithCaveats()` would
  // truncate off those new fields.

153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
  Orphan<Data> referenceExternalData(Data::Reader data) const;
  // Creates an Orphan<Data> that points at an existing region of memory (e.g. from another message)
  // without copying it.  There are some SEVERE restrictions on how this can be used:
  // - The memory must remain valid until the `MessageBuilder` is destroyed (even if the orphan is
  //   abandoned).
  // - Because the data is const, you will not be allowed to obtain a `Data::Builder`
  //   for this blob.  Any call which would return such a builder will throw an exception.  You
  //   can, however, obtain a Reader, e.g. via orphan.getReader() or from a parent Reader (once
  //   the orphan is adopted).  It is your responsibility to make sure your code can deal with
  //   these problems when using this optimization; if you can't, allocate a copy instead.
  // - `data.begin()` must be aligned to a machine word boundary (32-bit or 64-bit depending on
  //   the CPU).  Any pointer returned by malloc() as well as any data blob obtained from another
  //   Cap'n Proto message satisfies this.
  // - If `data.size()` is not a multiple of 8, extra bytes past data.end() up until the next 8-byte
  //   boundary will be visible in the raw message when it is written out.  Thus, there must be no
  //   secrets in these bytes.  Data blobs obtained from other Cap'n Proto messages should be safe
  //   as these bytes should be zero (unless the sender had the same problem).
  //
  // The array will actually become one of the message's segments.  The data can thus be adopted
  // into the message tree without copying it.  This is particularly useful when referencing very
  // large blobs, such as whole mmap'd files.

175 176
private:
  _::BuilderArena* arena;
177
  _::CapTableBuilder* capTable;
178

179 180
  inline explicit Orphanage(_::BuilderArena* arena, _::CapTableBuilder* capTable)
      : 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 186 187 188 189
  struct GetInnerReader;
  template <typename T>
  struct NewOrphanListImpl;

  friend class MessageBuilder;
190
  friend struct _::OrphanageInternal;
191 192 193 194 195 196 197
};

// =======================================================================================
// Inline implementation details.

namespace _ {  // private

198
template <typename T, Kind = CAPNP_KIND(T)>
199 200
struct OrphanGetImpl;

201 202 203 204 205 206 207
template <typename T>
struct OrphanGetImpl<T, Kind::PRIMITIVE> {
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, _::elementSizeForType<T>());
  }
};

208 209 210 211 212
template <typename T>
struct OrphanGetImpl<T, Kind::STRUCT> {
  static inline typename T::Builder apply(_::OrphanBuilder& builder) {
    return typename T::Builder(builder.asStruct(_::structSize<T>()));
  }
213 214 215
  static inline typename T::Reader applyReader(const _::OrphanBuilder& builder) {
    return typename T::Reader(builder.asStructReader(_::structSize<T>()));
  }
216 217 218
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, _::structSize<T>());
  }
219 220
};

221
#if !CAPNP_LITE
222 223 224 225 226 227 228 229
template <typename T>
struct OrphanGetImpl<T, Kind::INTERFACE> {
  static inline typename T::Client apply(_::OrphanBuilder& builder) {
    return typename T::Client(builder.asCapability());
  }
  static inline typename T::Client applyReader(const _::OrphanBuilder& builder) {
    return typename T::Client(builder.asCapability());
  }
230 231 232
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, ElementSize::POINTER);
  }
233
};
234
#endif  // !CAPNP_LITE
235

236 237
template <typename T, Kind k>
struct OrphanGetImpl<List<T, k>, Kind::LIST> {
238 239 240
  static inline typename List<T>::Builder apply(_::OrphanBuilder& builder) {
    return typename List<T>::Builder(builder.asList(_::ElementSizeForType<T>::value));
  }
241 242 243
  static inline typename List<T>::Reader applyReader(const _::OrphanBuilder& builder) {
    return typename List<T>::Reader(builder.asListReader(_::ElementSizeForType<T>::value));
  }
244 245 246
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, ElementSize::POINTER);
  }
247 248 249 250
};

template <typename T>
struct OrphanGetImpl<List<T, Kind::STRUCT>, Kind::LIST> {
251
  static inline typename List<T>::Builder apply(_::OrphanBuilder& builder) {
252 253
    return typename List<T>::Builder(builder.asStructList(_::structSize<T>()));
  }
254 255 256
  static inline typename List<T>::Reader applyReader(const _::OrphanBuilder& builder) {
    return typename List<T>::Reader(builder.asListReader(_::ElementSizeForType<T>::value));
  }
257 258 259
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, ElementSize::POINTER);
  }
260 261 262 263 264 265 266
};

template <>
struct OrphanGetImpl<Text, Kind::BLOB> {
  static inline Text::Builder apply(_::OrphanBuilder& builder) {
    return Text::Builder(builder.asText());
  }
267 268 269
  static inline Text::Reader applyReader(const _::OrphanBuilder& builder) {
    return Text::Reader(builder.asTextReader());
  }
270 271 272
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, ElementSize::POINTER);
  }
273 274 275 276 277 278 279
};

template <>
struct OrphanGetImpl<Data, Kind::BLOB> {
  static inline Data::Builder apply(_::OrphanBuilder& builder) {
    return Data::Builder(builder.asData());
  }
280 281 282
  static inline Data::Reader applyReader(const _::OrphanBuilder& builder) {
    return Data::Reader(builder.asDataReader());
  }
283 284 285
  static inline void truncateListOf(_::OrphanBuilder& builder, ElementCount size) {
    builder.truncate(size, ElementSize::POINTER);
  }
286 287
};

288 289 290 291 292
struct OrphanageInternal {
  static inline _::BuilderArena* getArena(Orphanage orphanage) { return orphanage.arena; }
  static inline _::CapTableBuilder* getCapTable(Orphanage orphanage) { return orphanage.capTable; }
};

293 294 295
}  // namespace _ (private)

template <typename T>
296
inline BuilderFor<T> Orphan<T>::get() {
297 298 299
  return _::OrphanGetImpl<T>::apply(builder);
}

300
template <typename T>
301
inline ReaderFor<T> Orphan<T>::getReader() const {
302 303 304
  return _::OrphanGetImpl<T>::applyReader(builder);
}

305 306
template <typename T>
inline void Orphan<T>::truncate(uint size) {
307
  _::OrphanGetImpl<ListElementType<T>>::truncateListOf(builder, bounded(size) * ELEMENTS);
308 309 310 311
}

template <>
inline void Orphan<Text>::truncate(uint size) {
312
  builder.truncateText(bounded(size) * ELEMENTS);
313 314 315 316
}

template <>
inline void Orphan<Data>::truncate(uint size) {
317
  builder.truncate(bounded(size) * ELEMENTS, ElementSize::BYTE);
318 319
}

320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335
template <typename T>
struct Orphanage::GetInnerBuilder<T, Kind::STRUCT> {
  static inline _::StructBuilder apply(typename T::Builder& t) {
    return t._builder;
  }
};

template <typename T>
struct Orphanage::GetInnerBuilder<T, Kind::LIST> {
  static inline _::ListBuilder apply(typename T::Builder& t) {
    return t.builder;
  }
};

template <typename BuilderType>
Orphanage Orphanage::getForMessageContaining(BuilderType builder) {
336 337
  auto inner = GetInnerBuilder<FromBuilder<BuilderType>>::apply(builder);
  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 346
}

template <typename T, Kind k>
struct Orphanage::NewOrphanListImpl<List<T, k>> {
347 348 349
  static inline _::OrphanBuilder apply(
      _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) {
    return _::OrphanBuilder::initList(
350
        arena, capTable, bounded(size) * ELEMENTS, _::ElementSizeForType<T>::value);
351 352 353 354 355
  }
};

template <typename T>
struct Orphanage::NewOrphanListImpl<List<T, Kind::STRUCT>> {
356 357 358
  static inline _::OrphanBuilder apply(
      _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) {
    return _::OrphanBuilder::initStructList(
359
        arena, capTable, bounded(size) * ELEMENTS, _::structSize<T>());
360 361 362 363 364
  }
};

template <>
struct Orphanage::NewOrphanListImpl<Text> {
365 366
  static inline _::OrphanBuilder apply(
      _::BuilderArena* arena, _::CapTableBuilder* capTable, uint size) {
367
    return _::OrphanBuilder::initText(arena, capTable, bounded(size) * BYTES);
368 369 370 371 372
  }
};

template <>
struct Orphanage::NewOrphanListImpl<Data> {
373 374
  static inline _::OrphanBuilder apply(
      _::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 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405
}

template <typename T>
struct Orphanage::GetInnerReader<T, Kind::STRUCT> {
  static inline _::StructReader apply(const typename T::Reader& t) {
    return t._reader;
  }
};

template <typename T>
struct Orphanage::GetInnerReader<T, Kind::LIST> {
  static inline _::ListReader apply(const typename T::Reader& t) {
    return t.reader;
  }
};

template <typename T>
struct Orphanage::GetInnerReader<T, Kind::BLOB> {
  static inline const typename T::Reader& apply(const typename T::Reader& t) {
    return t;
  }
};

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 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
template <typename T>
inline Orphan<List<ListElementType<FromReader<T>>>>
Orphanage::newOrphanConcat(kj::ArrayPtr<T> lists) const {
  return newOrphanConcat(kj::implicitCast<kj::ArrayPtr<const T>>(lists));
}
template <typename T>
inline Orphan<List<ListElementType<FromReader<T>>>>
Orphanage::newOrphanConcat(kj::ArrayPtr<const T> lists) const {
  // Optimization / simplification: Rely on List<T>::Reader containing nothing except a
  // _::ListReader.
  static_assert(sizeof(T) == sizeof(_::ListReader), "lists are not bare readers?");
  kj::ArrayPtr<const _::ListReader> raw(
      reinterpret_cast<const _::ListReader*>(lists.begin()), lists.size());
  typedef ListElementType<FromReader<T>> Element;
  return Orphan<List<Element>>(
      _::OrphanBuilder::concat(arena, capTable,
          _::elementSizeForType<Element>(),
          _::minStructSizeForElement<Element>(), raw));
}

431 432 433 434
inline Orphan<Data> Orphanage::referenceExternalData(Data::Reader data) const {
  return Orphan<Data>(_::OrphanBuilder::referenceExternalData(arena, data));
}

435
}  // namespace capnp
436 437

CAPNP_END_HEADER