[Hiper-related work] Added a function called curl_multi_assign() that will

set a private pointer added to the internal libcurl hash table for the
particular socket passed in to this function.

5 files changed, 102 insertions, 39 deletions

diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am
index e43a0b67c..ea96cea1d 100644
--- a/docs/libcurl/Makefile.am
+++ b/docs/libcurl/Makefile.am
@@ -18,7 +18,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3	 \
  curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3	 \
  libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3		 \
  curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3		 \
- curl_multi_timeout.3 curl_formget.3
+ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3
 
 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html		  \
  curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html	  \
@@ -35,8 +35,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html		  \
  libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html	  \
  curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \
  curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html	  \
- curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html		\
- curl_formget.html
+ curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html	  \
+ curl_formget.html curl_multi_assign.html
 
 PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
  curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf	  \
@@ -52,8 +52,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
  libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf	  \
  curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf	  \
  curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf	  \
- curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf	\
- curl_formget.pdf
+ curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf	  \
+ curl_formget.pdf curl_multi_assign.pdf
 
 CLEANFILES = $(HTMLPAGES) $(PDFPAGES)
 
diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3
index 0729ef787..ba15ad4e0 100644
--- a/docs/libcurl/curl_global_init.3
+++ b/docs/libcurl/curl_global_init.3
@@ -11,30 +11,30 @@ curl_global_init - Global libcurl initialisation
 .BI "CURLcode curl_global_init(long " flags ");"
 .ad
 .SH DESCRIPTION
-This function sets up the program environment that libcurl needs.  Think
-of it as an extension of the library loader.
+This function sets up the program environment that libcurl needs.  Think of it
+as an extension of the library loader.
 
-This function must be called at least once within a program (a program is
-all the code that shares a memory space) before the program calls any other
-function in libcurl.  The environment it sets up is constant for the life
-of the program and is the same for every program, so multiple calls have
-the same effect as one call.
+This function must be called at least once within a program (a program is all
+the code that shares a memory space) before the program calls any other
+function in libcurl.  The environment it sets up is constant for the life of
+the program and is the same for every program, so multiple calls have the same
+effect as one call.
 
 The flags option is a bit pattern that tells libcurl exactly what features to
 init, as described below. Set the desired bits by ORing the values together.
 In normal operation, you must specify CURL_GLOBAL_ALL.  Don't use any other
-value unless you are familiar with and mean to control internal operations
-of libcurl.
+value unless you are familiar with and mean to control internal operations of
+libcurl.
 
-\fBThis function is not thread safe.\fP  You must not call it when any
-other thread in the program (i.e. a thread sharing the same memory) is
-running.  This doesn't just mean no other thread that is using
-libcurl.  Because \fIcurl_global_init()\fP calls functions of other
-libraries that are similarly thread unsafe, it could conflict with any
-other thread that uses these other libraries.
+\fBThis function is not thread safe.\fP You must not call it when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This doesn't just mean no other thread that is using libcurl.  Because
+\fIcurl_global_init()\fP calls functions of other libraries that are similarly
+thread unsafe, it could conflict with any other thread that uses these other
+libraries.
 
-See the description in \fBlibcurl\fP(3) of global environment
-requirements for details of how to use this function.
+See the description in \fBlibcurl\fP(3) of global environment requirements for
+details of how to use this function.
 
 .SH FLAGS
 .TP 5
diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3
new file mode 100644
index 000000000..cb47a5e25
--- /dev/null
+++ b/docs/libcurl/curl_multi_assign.3
@@ -0,0 +1,44 @@
+.\" $Id$
+.\"
+.TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual"
+.SH NAME
+curl_multi_assign \- set data to associated with an internal socket
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
+                            void *sockptr);
+.SH DESCRIPTION
+This function assigns an association in the multi handle between the given
+socket and a private pointer of the application. This is (only) useful for
+\fIcurl_multi_socket(3)\fP uses.
+
+When set, the \fIsockptr\fP pointer will be passed to all future socket
+callbacks for the specific \fIsockfd\fP socket.
+
+If the given \fIsockfd\fP isn't already in use by libcurl, this function will
+return an error.
+
+libcurl only keeps one single pointer associated with a socket, so calling
+this function several times for the same socket will make the last set pointer
+get used.
+
+The idea here being that this association (socket to private pointer) is
+something that just about every application that uses this API will need and
+then libcurl can just as well do it since it already has an internal hash
+table lookup for this.
+.SH "RETURN VALUE"
+The standard CURLMcode for multi interface error codes.
+.SH "TYPICAL USAGE"
+In a typical application you allocate a struct or at least use some kind of
+semi-dynamic data for each socket that we must wait for action on when using
+the \fIcurl_multi_socket(3)\fP approach.
+
+When our socket-callback get called by libcurl and we get to know about yet
+another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
+the particular data so that when we get updates about this same socket again,
+we don't have to find the struct associated with this socket by ourselves.
+.SH AVAILABILITY
+This function was added in libcurl 7.15.5, although not deemed stable yet.
+.SH "SEE ALSO"
+.BR curl_multi_setopt "(3), " curl_multi_socket "(3) "
diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3
index 623daa53f..0228e3d64 100644
--- a/docs/libcurl/curl_multi_setopt.3
+++ b/docs/libcurl/curl_multi_setopt.3
@@ -25,8 +25,9 @@ the socket (file descriptor) status by doing none, one or multiple calls to
 the curl_socket_callback given in the \fBparam\fP argument. They update the
 status with changes since the previous time a \fIcurl_multi_socket(3)\fP
 function was called. If the given callback pointer is NULL, no callback will
-be called. Set the callback's fourth argument with \fICURLMOPT_SOCKETDATA\fP.
-See \fIcurl_multi_socket(3)\fP for more callback details.
+be called. Set the callback's \fBuserp\fP argument with
+\fICURLMOPT_SOCKETDATA\fP.  See \fIcurl_multi_socket(3)\fP for more callback
+details.
 .IP CURLMOPT_SOCKETDATA
 Pass a pointer to whatever you want passed to the curl_socket_callback's forth
 argument, the userp pointer. This is not used by libcurl but only passed-thru
diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3
index e5312c840..0c5ba7345 100644
--- a/docs/libcurl/curl_multi_socket.3
+++ b/docs/libcurl/curl_multi_socket.3
@@ -1,6 +1,6 @@
 .\" $Id$
 .\"
-.TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual"
+.TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual"
 .SH NAME
 curl_multi_socket \- reads/writes available data
 .SH SYNOPSIS
@@ -19,32 +19,41 @@ application has detected action on a socket handled by libcurl, it should call
 with the action.
 
 These functions inform the application about updates in the socket (file
-descriptor) status by doing none, one or multiple calls to the
-curl_socket_callback given with the CURLMOPT_SOCKETFUNCTION option to
+descriptor) status by doing none, one or multiple calls to the callback
+function set with the CURLMOPT_SOCKETFUNCTION option to
 \fIcurl_multi_setopt(3)\fP. They update the status with changes since the
 previous time this function was called.
 
-If you want to force libcurl to (re-)check all its internal sockets and
-transfers instead of just a single one, you call
-\fBcurl_multi_socket_all(3)\fP instead.
+To force libcurl to (re-)check all its internal sockets and transfers instead
+of just a single one, you call \fBcurl_multi_socket_all(3)\fP.
 
-An application should call \fBcurl_multi_timeout(3)\fP to figure out how long
-it should wait for socket actions \- at most \- before doing the timeout
-action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP
-argument set to CURL_SOCKET_TIMEOUT.
+Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to
+wait for socket actions \- at most \- before doing the timeout action: call
+the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to
+CURL_SOCKET_TIMEOUT.
+
+.SH "CALLBACK DETAILS"
 
 The socket \fBcallback\fP function uses a prototype like this
 .nf
 
-     int curl_socket_callback(CURL *easy,      /* easy handle */
-                              curl_socket_t s, /* socket */
-                              int action,      /* see values below */
-                              void *userp);    /* "private" pointer */
+  int curl_socket_callback(CURL *easy,      /* easy handle */
+                           curl_socket_t s, /* socket */
+                           int action,      /* see values below */
+                           void *userp,    /* private callback pointer */
+                           void *socketp); /* private socket pointer */
 
 .fi
 The callback MUST return 0.
 
-The \fIaction\fP (third) argument to the callback has one of five values:
+The \fIeasy\fP argument is a pointer to the easy handle that deals with this
+particular socket. Note that a single handle may work with several sockets
+simultaneously.
+
+The \fIs\fP argument is the actual socket value as you use it within your
+system.
+
+The \fIaction\fP argument to the callback has one of five values:
 .RS
 .IP "CURL_POLL_NONE (0)"
 register, not interested in readiness (yet)
@@ -57,6 +66,15 @@ register, interested in both read and write readiness
 .IP "CURL_POLL_REMOVE (4)"
 deregister
 .RE
+
+The \fIsocketp\fP argument is a private pointer you have previously set with
+\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
+pointer has been set, socketp will be NULL. This argument is of course a
+service to applications that want to keep certain data or structs that are
+strictly associated to the given socket.
+
+The \fIuserp\fP argument is a private pointer you have previously set with
+\fIcurl_multi_setopt(3)\fP and the CURLMOPT_SOCKETDATA option.
 .SH "RETURN VALUE"
 CURLMcode type, general libcurl multi interface error code.