diff --git a/c++/src/capnp/message.h b/c++/src/capnp/message.h index fc6e3312fb9e57f8d474e1f61e5b549a3092210b..4f1e8d3a60bc5844f7bb41f7accd26e3990952a1 100644 --- a/c++/src/capnp/message.h +++ b/c++/src/capnp/message.h @@ -183,13 +183,15 @@ public: // new objects in this message. virtual kj::ArrayPtr<word> allocateSegment(uint minimumSize) = 0; - // Allocates an array of at least the given number of words, throwing an exception or crashing if - // this is not possible. It is expected that this method will usually return more space than - // requested, and the caller should use that extra space as much as possible before allocating - // more. The returned space remains valid at least until the MessageBuilder is destroyed. + // Allocates an array of at least the given number of zero'd words, throwing an exception or + // crashing if this is not possible. It is expected that this method will usually return more + // space than requested, and the caller should use that extra space as much as possible before + // allocating more. The returned space remains valid at least until the MessageBuilder is + // destroyed. // - // Cap'n Proto will only call this once at a time, so the subclass need not worry about - // thread-safety. + // allocateSegment() is responsible for zeroing the memory before returning. This is required + // because otherwise the Cap'n Proto implementation would have to zero the memory anyway, and + // many allocators are able to provide already-zero'd memory more efficiently. template <typename RootType> typename RootType::Builder initRoot();