Document that Builders cannot be re-used?

[FrancisRussell]

From the documentation, it's unclear if Builders can be re-used. The presence of init_root() gives the impression that a Builder can be re-initialized for construction of a new message. Given that one wishes to avoid repeated memory allocations, this seems like an obvious thing to do, but attempting to do so results in increasingly larger messages (presumably all the previous messages concatenated, but I've not checked this in depth).

[dwrensha]

Yep, the init_ methods clear out the old data, but don't reclaim the old space. More documentation about this would be good.

[FrancisRussell]

Does this mean, as appeared to be the case, that a Builder cannot be re-used? If so, is this behaviour deliberate?

[dwrensha]

You can reuse a message::Builder, but the usefulness of doing so is limited because you will continue to accumulate unused memory that can only be reclaimed by dropping the message::Builder.

The best way to avoid allocations between messages is to use message::ScratchSpaceHeapAllocator. That allows you to specify a buffer that will be used for the first segment of your message and can be reused between messages.