Skip to content

CURLMOPT_MAX_PIPELINE_LENGTH and SETTINGS_MAX_CONCURRENT_STREAMS #1059

Closed
Closed
CURLMOPT_MAX_PIPELINE_LENGTH and SETTINGS_MAX_CONCURRENT_STREAMS#1059
Labels
HTTP/2documentation

Description

@jeroen
jeroen
opened on Oct 7, 2016

Currently the CURLMOPT_MAX_PIPELINE_LENGTH documentation states the default is 5. Is this also the case for HTTP/2 connections, i.e. whenCURLMOPT_PIPELINING is set to CURLPIPE_MULTIPLEX?

In this case, could we make an option that automatically sets CURLMOPT_MAX_PIPELINE_LENGTH to what the server specifies in SETTINGS_MAX_CONCURRENT_STREAMS? See also SO topic.

Activity

  1. bagder commented on Oct 7, 2016

    @bagder
    bagder
    on Oct 7, 2016
    Member

    That option is only used for actual pipelining, not for HTTP/2. libcurl will add transfers to the same connection as long as the peer allows (according to SETTINGS_MAX_CONCURRENT_STREAMS) and if you add even more transfers it will create a new connection for those. Unless you limit the number of connections.

  2. bagder
    added
    documentation
    HTTP/2
    on Oct 7, 2016

  3. bagder commented on Oct 8, 2016

    @bagder
    bagder
    on Oct 8, 2016
    Member

    Only used if pipelining is enabled.

    Is quite clearly mentioned in the docs. What else can we do to make that clearer?

  4. jeroen commented on Oct 10, 2016

    @jeroen
    jeroen
    on Oct 10, 2016
    ContributorAuthor

    So setting pipelining to multiplex does not mean pipelining is enabled?

    curl_multi_setopt(CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX)

  5. jay commented on Oct 10, 2016

    @jay
    jay
    on Oct 10, 2016
    Member

    I think the confusion here is they're really two separate things. Pipelining is HTTP/1.1 and Multiplexing is HTTP/2. They are similar enough (but not really..) that we piggybacked on the option CURLMOPT_PIPELINING. bagder has a better explanation of HTTP/2 multiplexing somewhere, but I don't recall where

  6. jeroen commented on Oct 10, 2016

    @jeroen
    jeroen
    on Oct 10, 2016
    ContributorAuthor

    I get that but given that multiplexing is enabled via CURLMOPT_PIPELINING then one might think that libcurl conceptualizes it as a form of pipelining, hence CURLMOPT_MAX_PIPELINE_LENGTH applies...

    If this is not the case then it should have been another CURLMOPT I think...

  7. jay commented on Oct 10, 2016

    @jay
    jay
    on Oct 10, 2016
    Member

    That seems like a fair point, so I think where we're at is either improve CURLMOPT_MAX_PIPELINE_LENGTH.3 doc or make it so that option overrides SETTINGS_MAX_CONCURRENT_STREAMS, if that's acceptable.

  8. jeroen commented on Oct 10, 2016

    @jeroen
    jeroen
    on Oct 10, 2016
    ContributorAuthor

    I think my confusion simply comes from this:

    That option is only used for actual pipelining, not for HTTP/2.

    How are users supposed to know that http/2 multiplex is not considered "actual pipelining" even though the user has to enable it via:

    curl_multi_setopt(CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX)

    This is simply confusing. You need to emphasize in the documentation for CURLMOPT_PIPELINING that the value for CURLPIPE_MULTIPLEX is not actual pipelining (whatever that may mean) and in the docs for CURLMOPT_MAX_PIPELINE_LENGTH that the option does not apply for CURLPIPE_MULTIPLEX pipes.

  9. bagder commented on Oct 10, 2016

    @bagder
    bagder
    on Oct 10, 2016
    Member

    Maybe we should instead phrase it like:

    "This option is only used for HTTP/1 Pipelining, not for HTTP/2 multiplexing"

  10. jay commented on Oct 10, 2016

    @jay
    jay
    on Oct 10, 2016
    Member

    well it is titled "CURLMOPT_PIPELINING - enable HTTP pipelining and multiplexing " and I think the description makes it clear there are two distinct features. for CURLMOPT_MAX_PIPELINE_LENGTH like I said I think you have a point. if we change the documentation it could be

    diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
index cac3c71..1bb10a2 100644
--- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
+++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
@@ -29,8 +29,8 @@ CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline
 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, long max);
 .SH DESCRIPTION
 Pass a long. The set \fBmax\fP number will be used as the maximum amount of
-outstanding requests in a pipelined connection. Only used if pipelining is
-enabled.
+outstanding requests in an HTTP/1.1 pipelined connection. Only used if
+HTTP/1.1 pipelining is enabled.

 When this limit is reached, libcurl will use another connection to the same
 host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until

  11. bagder commented on Oct 15, 2016

    @bagder
    bagder
    on Oct 15, 2016
    Member

    @jeroenooms so can you tell us what if anything you think can improve the docs to make this more apparent?

  12. jay
    added a commit that references this issue on Oct 28, 2016

    CURLMOPT_MAX_PIPELINE_LENGTH.3: Clarify it's not for HTTP/2

    568037f

  13. jay commented on Oct 28, 2016

    @jay
    jay
    on Oct 28, 2016
    Member

    The documentation has been updated to make it clearer this is only for HTTP/1.1. Thanks

  14. jay
    closed this as completedon Oct 28, 2016
  15. lock
    locked as resolved and limited conversation to collaborators on May 7, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    HTTP/2documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions