byte-stream.capnp (1815B)
1 @0x8f5d14e1c273738d; 2 3 $import "/capnp/c++.capnp".namespace("capnp"); 4 5 interface ByteStream { 6 write @0 (bytes :Data) -> stream; 7 # Write a chunk. 8 9 end @1 (); 10 # Signals clean EOF. (If the ByteStream is dropped without calling this, then the stream was 11 # prematurely canceled and so the body should not be considered complete.) 12 13 getSubstream @2 (callback :SubstreamCallback, 14 limit :UInt64 = 0xffffffffffffffff) -> (substream :ByteStream); 15 # This method is used to implement path shortening optimization. It is designed in particular 16 # with KJ streams' pumpTo() in mind. 17 # 18 # getSubstream() returns a new stream object that can be used to write to the same destination 19 # as this stream. The substream will operate until it has received `limit` bytes, or its `end()` 20 # method has been called, whichever occurs first. At that time, it invokes one of the methods of 21 # `callback` based on the termination condition. 22 # 23 # While a substream is active, it is an error to call write() on the original stream. Doing so 24 # may throw an exception or may arbitrarily interleave bytes with the substream's writes. 25 26 interface SubstreamCallback { 27 ended @0 (byteCount :UInt64); 28 # `end()` was called on the substream after writing `byteCount` bytes. The `end()` call was 29 # NOT forwarded to the underlying stream, which remains open. 30 31 reachedLimit @1 () -> (next :ByteStream); 32 # The number of bytes specified by the `limit` parameter of `getSubstream()` was reached. 33 # The substream will "resolve itself" to `next`, so that all future calls to the substream 34 # are forwarded to `next`. 35 # 36 # If the `write()` call which reached the limit included bytes past the limit, then the first 37 # `write()` call to `next` will be for those leftover bytes. 38 } 39 }