mods

lib/multi.c

@@ -237,8 +237,5 @@ CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles)
 
 CURLMcode curl_multi_cleanup(CURLM *multi_handle);
 
-int curl_multi_info_open(CURLM *multi_handle, CURLMinfo *info_handle);
+CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue);
 
-CURLMsg *curl_multi_info_read(CURLMinfo *info_handle);
-
-void curl_multi_info_close(CURLMinfo *info_handle);

lib/multi.h

@@ -38,8 +38,8 @@
   o Enable a "pull" interface. The application that uses libcurl decides where
     and when to ask libcurl to get/send data.
 
-  o Enable multiple simultaneous transfers without using threads or making it
-    very complicated for the application.
+  o Enable multiple simultaneous transfers in the same thread without making it
+    complicated for the application.
 
   o Enable the application to select() on its own file descriptors and curl's
     file descriptors simultaneous easily.
@@ -71,40 +71,48 @@ typedef struct CURLMsg CURLMsg;
 typedef void * CURLMinfo;
 
 /*
- * Desc:    inititalize multi-style curl usage
  * Name:    curl_multi_init()
+ *
+ * Desc:    inititalize multi-style curl usage
  * Returns: a new CURLM handle to use in all 'curl_multi' functions.
  */
 CURLM *curl_multi_init(void);
 
 /*
- * Desc:    add a standard curl handle to the multi stack
  * Name:    curl_multi_add_handle()
- * Returns: CURLMcode type, general error code.
+ *
+ * Desc:    add a standard curl handle to the multi stack
+ * Returns: CURLMcode type, general multi error code.
  */
 CURLMcode curl_multi_add_handle(CURLM *multi_handle,
                                 CURL *curl_handle);
 
  /*
-  * Desc:    removes a curl handle from the multi stack again
   * Name:    curl_multi_remove_handle()
-  * Returns: CURLMcode type, general error code.
+  *
+  * Desc:    removes a curl handle from the multi stack again
+  * Returns: CURLMcode type, general multi error code.
   */
 CURLMcode curl_multi_remove_handle(CURLM *multi_handle,
                                    CURL *curl_handle);
 
  /*
+  * Name:    curl_multi_fdset()
+  *
   * Desc:    Ask curl for its fd_set sets. The app can use these to select() or
   *          poll() on. We want curl_multi_perform() called as soon as one of
   *          them are ready.
-  * Name:    curl_multi_fdset()
-  * Returns: CURLMcode type, general error code.
+  * Returns: CURLMcode type, general multi error code.
   */
 CURLMcode curl_multi_fdset(CURLM *multi_handle,
-                           fd_set *read_fd_set, fd_set *write_fd_set,
-                           fd_set *exc_fd_set, int *max_fd);
+                           fd_set *read_fd_set,
+                           fd_set *write_fd_set,
+                           fd_set *exc_fd_set,
+                           int *max_fd);
 
  /*
+  * Name:    curl_multi_perform()
+  *
   * Desc:    When the app thinks there's data available for curl it calls this
   *          function to read/write whatever there is right now. This returns
   *          as soon as the reads and writes are done. This function does not
@@ -112,60 +120,38 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle,
   *          data can be written, it can be called just in case. It returns
   *          the number of handles that still transfer data in the second
   *          argument's integer-pointer.
-  * Name:    curl_multi_fdset()
-  * Returns: CURLMcode type, general error code. *NOTE* that this only returns
-  *          errors etc regardin the whole multi stack. There might still have
-  *          occurred problems on invidual transfers even when this returns OK.
+  *
+  * Returns: CURLMcode type, general multi error code. *NOTE* that this only
+  *          returns errors etc regarding the whole multi stack. There might
+  *          still have occurred problems on invidual transfers even when this
+  *          returns OK.
   */
-
-CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
+CURLMcode curl_multi_perform(CURLM *multi_handle,
+                             int *running_handles);
 
  /*
-  * Desc:    Cleans up and removes a whole multi stack.
   * Name:    curl_multi_cleanup()
-  * Returns: CURLMcode type, general error code.
+  *
+  * Desc:    Cleans up and removes a whole multi stack. It does not free or
+  *          touch any individual easy handles in any way. We need to define
+  *          in what state those handles will be if this function is called
+  *          in the middle of a transfer.
+  * Returns: CURLMcode type, general multi error code.
   */
 CURLMcode curl_multi_cleanup(CURLM *multi_handle);
 
-/* ---------------------------------------------------------------------- */
 /*
- * I suggest an fopen style system to get information from the multi layer.
- * I've named these functions "curl_multi_info*" something to make it apparent
- * that they belong together.
+ * Name:    curl_multi_info_read()
  *
- * I expect that the curl_multi_info_open will be used fairly often after
- * calls to curl_multi_perform(), but there's nothing in this design that
- * forces the application to invoke it at that particular time. In fact, many
- * applications will do good without using it at all.  */
-
-/*
  * Desc:    Ask the multi handle if there's any messages/informationals from
- *          the individual transfers. We pass a pointer to a 'CURLMinfo' that
- *          can be used as input in a subsequent call to curl_multi_info_read.
- *
- *          Messages include informationals such as error code from the
- *          transfer or just the fact that a transfer is completed. More
- *          details on these should be written down as well.
- *
- * Name:    curl_multi_info_open()
- * Returns: The number of transfers that have information stored that can be
- *          read. If zero is returned, there's no need to call
- *          curl_multi_info_close() on the returned handle, but there's no
- *          harm in doing so.
- */
-int curl_multi_info_open(CURLM *multi_handle, CURLMinfo *info_handle);
-
-/*
- * Desc:    Returns a pointer to a filled-in struct with information.
+ *          the individual transfers. Messages include informationals such as
+ *          error code from the transfer or just the fact that a transfer is
+ *          completed. More details on these should be written down as well.
  *
  *          Repeated calls to this function will return a new struct each
  *          time, until a special "end of msgs" struct is returned as a signal
  *          that there is no more to get at this point.
  *
- *          curl_multi_info_close() should be called when the last info has
- *          been read. In fact, it must be called if curl_multi_info_open()
- *          was called.
- *
  *          The data the returned pointer points to will not survive calling
  *          curl_multi_cleanup().
  *
@@ -177,24 +163,12 @@ int curl_multi_info_open(CURLM *multi_handle, CURLMinfo *info_handle);
  *          must never expose complex structs to applications, as then we'll
  *          undoubtably get backwards compatibility problems in the future.
  *
- * Name:    curl_multi_info_read()
- *
- * Returns: A pointer to a struct, or NULL if it failed or ran out of structs.
- *          Note that if you continue reading until you get a NULL, you did
- *          read at least one too many times!
+ * Returns: A pointer to a filled-in struct, or NULL if it failed or ran out
+ *          of structs. It also writes the number of messages left in the
+ *          queue (after this read) in the integer the second argument points
+ *          to.
  */
-CURLMsg *curl_multi_info_read(CURLMinfo *info_handle);
-
-/*
- * Desc:    Terminates an info reading "session".
- *
- * Name:    curl_multi_info_close()
- *
- * Returns: When we've read all the info we want from the info_handle, we
- *          signal this to the multi system by calling this function.
- *          After this call, the info_handle can no longer be used.
- *
- */
-void curl_multi_info_close(CURLMinfo *info_handle);
+CURLMsg *curl_multi_info_read(CURLM *multi_handle,
+                              int *msgs_in_queue);
 
 #endif