lib: ostream-multiplex - Mark the PACKET format deprecated

The original packet-based framing requires the parent ostream to buffer a
whole packet and cannot stream to a parent with max_buffer_size==0, so it
does not work with senders that stream directly to the socket. New code
should use the STREAM format; PACKET is kept only for backwards
compatibility and is being phased out.

diff --git a/src/lib/ostream-multiplex.h b/src/lib/ostream-multiplex.h
index 1e9ea88f351d2e2e11705bda2827aa2ae1e9fdf4..1ad2107c4694f531f438c16f728205fd13774240 100644 (file)
--- a/src/lib/ostream-multiplex.h
+++ b/src/lib/ostream-multiplex.h
@@ -2,6 +2,14 @@
 #define OSTREAM_MULTIPLEX 1
 
 enum ostream_multiplex_format {
+       /* DEPRECATED: The original packet-based framing
+          (<channel-id><32bit length><data>). It can't stream to a parent
+          with max_buffer_size==0 and requires the parent to buffer a whole
+          packet, so it doesn't work with senders that stream directly to the
+          socket (e.g. imap-fetch). New code should use
+          OSTREAM_MULTIPLEX_FORMAT_STREAM. Kept only for backwards
+          compatibility with peers that don't yet understand the stream
+          format, and is being phased out. */
        OSTREAM_MULTIPLEX_FORMAT_PACKET,
        /* Start a new multiplex ostream */
        OSTREAM_MULTIPLEX_FORMAT_STREAM,