CMakeLua/Utilities/cmcurl-7.19.0/lib/README.multi_socket

   1 Implementation of the curl_multi_socket API
   2
   3   The main ideas of the new API are simply:
   4
   5    1 - The application can use whatever event system it likes as it gets info
   6        from libcurl about what file descriptors libcurl waits for what action
   7        on. (The previous API returns fd_sets which is very select()-centric).
   8
   9    2 - When the application discovers action on a single socket, it calls
  10        libcurl and informs that there was action on this particular socket and
  11        libcurl can then act on that socket/transfer only and not care about
  12        any other transfers. (The previous API always had to scan through all
  13        the existing transfers.)
  14
  15   The idea is that curl_multi_socket() calls a given callback with information
  16   about what socket to wait for what action on, and the callback only gets
  17   called if the status of that socket has changed.
  18
  19   In the API draft from before, we have a timeout argument on a per socket
  20   basis and we also allowed curl_multi_socket() to pass in an 'easy handle'
  21   instead of socket to allow libcurl to shortcut a lookup and work on the
  22   affected easy handle right away. Both these turned out to be bad ideas.
  23
  24   The timeout argument was removed from the socket callback since after much
  25   thinking I came to the conclusion that we really don't want to handle
  26   timeouts on a per socket basis. We need it on a per transfer (easy handle)
  27   basis and thus we can't provide it in the callbacks in a nice way. Instead,
  28   we have to offer a curl_multi_timeout() that returns the largest amount of
  29   time we should wait before we call the "timeout action" of libcurl, to
  30   trigger the proper internal timeout action on the affected transfer. To get
  31   this to work, I added a struct to each easy handle in which we store an
  32   "expire time" (if any). The structs are then "splay sorted" so that we can
  33   add and remove times from the linked list and yet somewhat swiftly figure
  34   out 1 - how long time there is until the next timer expires and 2 - which
  35   timer (handle) should we take care of now. Of course, the upside of all this
  36   is that we get a curl_multi_timeout() that should also work with old-style
  37   applications that use curl_multi_perform().
  38
  39   We also added a timer callback that makes libcurl call the application when
  40   the timeout value changes, and you set that with curl_multi_setopt().
  41
  42   We created an internal "socket to easy handles" hash table that given
  43   a socket (file descriptor) return the easy handle that waits for action on
  44   that socket.  This hash is made using the already existing hash code
  45   (previously only used for the DNS cache).
  46
  47   To make libcurl able to report plain sockets in the socket callback, we had
  48   to re-organize the internals of the curl_multi_fdset() etc so that the
  49   conversion from sockets to fd_sets for that function is only done in the
  50   last step before the data is returned. I also had to extend c-ares to get a
  51   function that can return plain sockets, as that library too returned only
  52   fd_sets and that is no longer good enough. The changes done to c-ares have
  53   been committed and are available in the c-ares CVS repository destined to be
  54   included in the c-ares 1.3.1 release.
  55
  56   We have done a test runs with up to 9000 connections (with a single active
  57   one). The curl_multi_socket() invoke then takes less than 10 microseconds in
  58   average (using the read-only-1-byte-at-a-time hack).  We are now below the
  59   60 microseconds "per socket action" goal (the extra 50 is the time libevent
  60   needs).
  61
  62 Status Right Now
  63
  64   The curl_multi_socket() API is implemented according to how it is
  65   documented. We deem it ready to use.
  66
  67     http://curl.haxx.se/libcurl/c/curl_multi_socket.html
  68     http://curl.haxx.se/libcurl/c/curl_multi_timeout.html
  69     http://curl.haxx.se/libcurl/c/curl_multi_setopt.html
  70
  71 What is Left for the curl_multi_socket API
  72
  73   Real world usage!