[v2,2/5] remote-curl: improve readability of curl callbacks

Commit Message

Jiří Hruška Nov. 15, 2023, 3:34 a.m. UTC

The "user data" or "context" argument of libcurl streaming callbacks
is sometimes called `clientp` and sometimes `buffer_`. The latter is
especially confusing, because there is an actual buffer pointer
argument passed to the same functions.

- Make the argument consistently named `userdata` everywhere, just
  like the official cURL documentation calls it.

- Also add comments to all the callbacks, to make it easier to grasp
  what is the "in" and what is the "out" direction in this code.

Signed-off-by: Jiri Hruska <[e-mail]>
---
 remote-curl.c | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)


@@ -725,9 +732,16 @@ static size_t rpc_out(void *ptr, size_t eltsize,
 	return avail;
 }

-static int rpc_seek(void *clientp, curl_off_t offset, int origin)
+/*
+ * CURLOPT_SEEKFUNCTION callback, called by libcurl when it wants to seek in
+ * the data being sent out. Used only if the request did not fit into just
+ * one buffer and data must be streamed as it comes.
+ * Has the same semantics as fseek(), but seeks in the buffered packet read
+ * from the pipe from the child process instead.
+ */
+static int rpc_seek(void *userdata, curl_off_t offset, int origin)
 {
-	struct rpc_state *rpc = clientp;
+	struct rpc_state *rpc = userdata;

 	if (origin != SEEK_SET)
 		BUG("rpc_seek only handles SEEK_SET, not %d", origin);
@@ -797,14 +811,15 @@ struct rpc_in_data {
 };

 /*
- * A callback for CURLOPT_WRITEFUNCTION. The return value is the bytes consumed
- * from ptr.
+ * CURLOPT_WRITEFUNCTION callback, called when more received data has come in.
+ * Has the same semantics as fwrite(), but writes packets to the pipe to the
+ * child process instead. The return value is the bytes consumed from ptr.
  */
 static size_t rpc_in(char *ptr, size_t eltsize,
-		size_t nmemb, void *buffer_)
+		size_t nmemb, void *userdata)
 {
 	size_t size = eltsize * nmemb;
-	struct rpc_in_data *data = buffer_;
+	struct rpc_in_data *data = userdata;
 	long response_code;

 	if (curl_easy_getinfo(data->slot->curl, CURLINFO_RESPONSE_CODE,

Patch

diff --git a/remote-curl.c b/remote-curl.c
index 199c4615a5..428dd70aa1 100644
--- a/remote-curl.c
+++ b/remote-curl.c
@@ -675,11 +675,18 @@  static int rpc_read_from_out(struct rpc_state
*rpc, int options,
 	return 1;
 }

+/*
+ * CURLOPT_READFUNCTION callback, called by libcurl when it wants more data
+ * to send out. Used only if the request did not fit into just one buffer and
+ * data must be streamed as it comes.
+ * Has the same semantics as fread(), but reads packets from the pipe from
+ * the child process instead. A return value of 0 (EOF) finishes the upload.
+ */
 static size_t rpc_out(void *ptr, size_t eltsize,
-		size_t nmemb, void *buffer_)
+		size_t nmemb, void *userdata)
 {
 	size_t max = eltsize * nmemb;
-	struct rpc_state *rpc = buffer_;
+	struct rpc_state *rpc = userdata;
 	size_t avail = rpc->len - rpc->pos;
 	enum packet_read_status status;