From 60222ae7c3999ef390bd61d70af7bd20baa57af1 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 24 Sep 2016 10:42:50 +0900 Subject: [PATCH] Update doc --- doc/programmers-guide.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/programmers-guide.rst b/doc/programmers-guide.rst index f49663b6..2e763a40 100644 --- a/doc/programmers-guide.rst +++ b/doc/programmers-guide.rst @@ -206,6 +206,10 @@ default transmission order does not fit, it has to schedule frames by itself using the callbacks (e.g., :type:`nghttp2_on_frame_send_callback`). +RST_STREAM has special side effect when it is submitted by +`nghttp2_submit_rst_stream()`. It cancels all pending HEADERS and +DATA frames whose stream ID matches the one in the RST_STREAM frame. +This may cause unexpected behaviour for the application in some cases. 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: @@ -215,12 +219,12 @@ above, the following code does not work: 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()`. - +RST_STREAM cancels HEADERS (and DATA), and just RST_STREAM is sent. The correct way is use :type:`nghttp2_on_frame_send_callback`, and after HEADERS and DATA frames are sent, issue -`nghttp2_submit_rst_stream()`. +`nghttp2_submit_rst_stream()`. FYI, +:type:`nghttp2_on_frame_not_send_callback` tells you why frames are +not sent. Implement user defined HTTP/2 non-critical extensions -----------------------------------------------------