Merge pull request #1743 from private-octopus/memory-copy-doc

Memory and copies doc

doc/managing-memory-copies.md

@@ -0,0 +1,87 @@
+# Managing Memory Copies
+
+Picoquic is designed to limit the number of memory copies and
+related memory allocations when sending and receiving data.
+
+## Memory copies when sending data
+
+Application data is sent as either data frames or stream frames.
+The sending process will format packets, send them, and
+also keep them in memory for possible repetitions.
+
+The typical flow would be:
+
+1. The application makes the data available, either by calling the API `picoquic_add_to_stream`
+   which allocates memory and keep a copy, or by signalling that data is available on a stream
+   using `picoquic_mark_active_stream`, or by signalling that datagrams are ready to send
+   using `picoquic_mark_datagram_ready`.
+2. The socket loop wakes up and calls the API `picoquic_prepare_next_packet_ex`
+   to ask the stack to prepare the next packet in the QUIC context. It provides
+   a data buffer in which the packet will be copied before being sent.
+3. The QUIC context selects the next avalaible connection, and will
+   call the function `picoquic_prepare_packet_ex` to prepare the next packet for that connection.
+4. That function allocates a packet container of type `picoquic_packet_t`, which will
+   contain the formatted packet.
+5. The formatting happens in the functions called from there, which will copy
+   a set of QUIC frames in the packet, including datagram or stream data frames.
+6. The content of the stream frames is either copied from data previously queued
+   using the `picoquic_add_to_stream` API, or copied directly from the application
+   memory using a callback `picoquic_callback_prepare_to_send` for streams, or
+   `picoquic_callback_prepare_datagram` for datagrams.
+7. When the packet is ready, the stack encrypt it. The clear text in the `packet` structure
+   is left untouched, and the encrypted bytes are copied into the "send" buffer
+   passed in `picoquic_prepare_next_packet_ex` call. That buffer will be sent to
+   the peer through a socket call.
+8. The clear text packet is attached to the retransmission queue, waiting for acknowledgement.
+
+### Handling packet losses
+
+In most cases, the clear text packet will be detached from the retransmission queue when the
+acknowledgement is received. In some cases, the acknowledgement is not received, and
+the data will have to be resent. For stream data, this will involve copying the stream data
+from the old copy into a new packet.
+
+### Recycling packets
+
+When packets are acknowledged, the `picoquic_packet_t` element is "recycled". It is added
+to a queue of empty packets managed in the Quic context, unless that queue has already
+reached its maximum size, in which case the packets are freed. New packet structures are
+only allocated when no recycled packet is available.
+
+## Memory copies when receiving data.
+
+The picoquic stack receives encrypted packets from the network, and delivers
+decrypted data to the application.
+
+The typical flow would be:
+
+1. A new network packet is received from the socket, and is passed to the
+   stack through a call to `picoquic_incoming_packet`.
+2. The stack allocates a data node container of type `picoquic_stream_data_node_t`.
+3. The header is analyzed and the packet is decrypted, with the clear text data
+   is stored into the data node.
+4. The decrypted packet is parsed, and the frames that it contained are processed. 
+   The content of datagram frames is passed to the application through the
+   callback `picoquic_callback_datagram`. The processing of stream data frames varies,
+   because stream data must be delivered in order.
+5. If the stream data is arriving in order, the data is delivered immediately,
+   through the callback `picoquic_callback_stream_data` or `picoquic_callback_stream_fin`.
+6. If the data cannot be delivered immediately, it needs to be kept in memory
+   until the holes in the stream have been filled. The processing varies
+   depending on the number of frames in the packet.
+7. If the stream data frame is the last frame in the packet, the data node
+   structured in queued to the stream. Else, a new data node is allocated,
+   the stream data frame is copied to it, and that new data node is queued
+   to the stream.
+8. At the end of this process, if the data node was not queued to a stream it
+   is recycled.
+
+### Managing out of order delivery
+
+When stream data frames arrive out of order, one data node is queued for
+each incoming frame. When a hole filling frame arrives, the data is delivered
+through the callback `picoquic_callback_stream_data` and the data node
+is recycled. The data nodes will also be recycled if the stream is reset
+or the connection is closed.
+
+