title: Stream while serializing with Cap'n'Proto
body: <p>Consider a Cap'n'Proto schema like this:</p>
  
  <pre><code>struct Document {
    header @0 : Header;
    records @1 :List(Record); // usually large number of records.
    footer @2 :Footer;
  }
  struct Header { numberOfRecords : UInt32; /* some fields */ };
  struct Footer { /* some fields */ };
  struct Record {
     type : UInt32;
     desc : Text;
     /* some more fields, relatively large in total */
  }
  </code></pre>
  
  <p>Now I want to serialize (i.e. build) a document instance and stream it to a remote destination.</p>
  
  <p>Since the document is usually very large I don't want to completely build it in memory before sending it. Instead I am looking for a builder that directly sends struct by struct over the wire. Such that the additional needed memory buffer is constant (i.e. O(max(sizeof(Header), sizeof(Record), sizeof(Footer))).</p>
  
  <p>Looking at the tutorial material I don't find such a builder. The <code>MallocMessageBuilder</code> seems to create everything in memory first (then you call <code>writeMessageToFd</code> on it).</p>
  
  <p>Does the Cap'n'Proto API support such a use-case?</p>
  
  <p>Or is Cap'n'Proto more meant to be used for messages that fit into memory before sending?</p>
  
  <p>In this example, the Document struct could be omitted and then one could just send a sequence of one Header message, n Record messages and one Footer. Since a Cap'n'Proto message is self-delimiting, this should work. But you loose your document root - perhaps sometimes this is not really an option.</p>