Document how libnghttp2 schedules HTTP/2 frames internally

doc/programmers-guide.rst

@@ -177,6 +177,51 @@ Any deviation results in stream error of type PROTOCOL_ERROR.  If
 error is found in PUSH_PROMISE frame, stream error is raised against
 promised stream.
 
+The order of transmission of the HTTP/2 frames
+----------------------------------------------
+
+This section describes the internals of libnghttp2 about the
+scheduling of transmission of HTTP/2 frames.  This is pretty much
+internal stuff, so the details could change in the future versions of
+the library.
+
+libnghttp2 categorizes HTTP/2 frames into 4 categories: urgent,
+regular, syn_stream, and data in the order of higher priority.
+
+The urgent category includes PING and SETTINGS.  They are sent with
+highest priority.  The order inside the category is FIFO.
+
+The regular category includes frames other than PING, SETTINGS, DATA,
+and HEADERS which does not create stream (which counts toward
+concurrent stream limit).  The order inside the category is FIFO.
+
+The syn_stream category includes HEADERS frame which creates stream,
+that counts toward the concurrent stream limit.
+
+The data category includes DATA frame, and the scheduling among DATA
+frames are determined by HTTP/2 dependency tree.
+
+If the application wants to send frames in the specific order, and the
+default transmission order does not fit, it has to schedule frames by
+itself using the callbacks (e.g.,
+:type:`nghttp2_on_frame_send_callback`).
+
+For example, suppose that application wants to send RST_STREAM after
+sending response HEADERS and DATA.  Because of the reason we mentioned
+above, the following code does not work:
+
+.. code-block:: c
+
+    nghttp2_submit_response(...)
+    nghttp2_submit_rst_stream(...)
+
+This is because HEADERS submitted by `nghttp2_submit_response()` is
+scheduled after RST_STREAM submitted by `nghttp2_submit_rst_stream()`.
+
+The correct way is use :type:`nghttp2_on_frame_send_callback`, and
+after HEADERS and DATA frames are sent, issue
+`nghttp2_submit_rst_stream()`.
+
 Implement user defined HTTP/2 non-critical extensions
 -----------------------------------------------------