Git init

1 files changed, 51 insertions, 0 deletions

diff --git a/lib/README.pipelining b/lib/README.pipelining
new file mode 100644
index 0000000..c7b4622
--- /dev/null
+++ b/lib/README.pipelining
@@ -0,0 +1,51 @@
+HTTP Pipelining with libcurl
+============================
+
+Background
+
+Since pipelining implies that one or more requests are sent to a server before
+the previous response(s) have been received, we only support it for multi
+interface use.
+
+Considerations
+
+When using the multi interface, you create one easy handle for each transfer.
+Bascially any number of handles can be created, added and used with the multi
+interface - simultaneously. It is an interface designed to allow many
+simultaneous transfers while still using a single thread. Pipelining does not
+change any of these details.
+
+API
+
+We've added a new option to curl_multi_setopt() called CURLMOPT_PIPELINING
+that enables "attempted pipelining" and then all easy handles used on that
+handle will attempt to use an existing pipeline.
+
+Details
+
+- A pipeline is only created if a previous connection exists to the same IP
+  address that the new request is being made to use.
+
+- Pipelines are only supported for HTTP(S) as no other currently supported
+  protocol has features resemembling this, but we still name this feature
+  plain 'pipelining' to possibly one day support it for other protocols as
+  well.
+
+- HTTP Pipelining is for GET and HEAD requests only.
+
+- When a pipeline is in use, we must take precautions so that when used easy
+  handles (i.e those who still wait for a response) are removed from the multi
+  handle, we must deal with the outstanding response nicely.
+
+- Explicitly asking for pipelining handle X and handle Y won't be supported.
+  It isn't easy for an app to do this association. The lib should probably
+  still resolve the second one properly to make sure that they actually _can_
+  be considered for pipelining. Also, asking for explicit pipelining on handle
+  X may be tricky when handle X get a closed connection.
+
+- We need options to control max pipeline length, and probably how to behave
+  if we reach that limit. As was discussed on the list, it can probably be
+  made very complicated, so perhaps we can think of a way to pass all
+  variables involved to a callback and let the application decide how to act
+  in specific situations. Either way, these fancy options are only interesting
+  to work on when everything is working and we have working apps to test with.