GNURLMOPT_TIMERFUNCTION(3)

🦋 GNURLMOPT_TIMERFUNCTION(3) 🦋

okay bestie, this is the GNURLMOPT_TIMERFUNCTION(3) page from the curl_multi_setopt options manual, and it's literally about giving libcurl a timer callback. no cap, it's giving main-character callback energy ✨

🌸 NAME 🌸

• CURLMOPT_TIMERFUNCTION — set callback to receive timeout values 💅

✨ SYNOPSIS ✨

include this and match the callback shape exactly, bestie:

#include <gnurl/curl.h>

int timer_callback(CURLM *multi,    /* multi handle */
                   long timeout_ms, /* timeout in number of ms */
                   void *userp);    /* private callback pointer */

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);

💖 DESCRIPTION 💖

You pass a pointer to your callback function, and it should match the prototype up there ⬆️.

Some features — think timeouts and retries — require you to call libcurl even when there's zero activity on the file descriptors. lowkey important 🫶

Your callback function timer_callback should install a non-repeating timer with an interval of timeout_ms. When that timer fires, call either curl_multi_socket_action(3) or curl_multi_perform(3), depending on which interface you use. pick your fighter 💅

A timeout_ms value of -1 passed to this callback means you should delete the timer. All other values are valid expire times in number of milliseconds. fr fr, -1 is the "bestie, cancel the timer" signal 🙈

The timer_callback will only be called when the timeout expire time is changed. that's the vibe check ⭐

The userp pointer is set with CURLMOPT_TIMERDATA(3). 🎀

The timer callback should return 0 on success, and -1 on error. This callback can be used instead of, or in addition to, curl_multi_timeout(3). iykyk 🌈

WARNING 🚨 even if it feels tempting, avoid calling libcurl directly from within the callback itself when the timeout_ms value is zero, since it risks triggering an unpleasant recursive behavior that immediately calls another call to the callback with a zero timeout... 💀

🎀 DEFAULT 🎀

NULL — that's it, that's the default 🙈

🌈 PROTOCOLS 🌈

All 🦋

🍓 EXAMPLE 🍓

here's the exact example, copied with love and zero edits:

static gboolean timeout_cb(gpointer user_data)
{
  int running;
  if(user_data) {
    g_free(user_data);
    curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
  }
  curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
  return G_SOURCE_REMOVE;
}

static int timerfunc(CURLM *multi, long timeout_ms, void *userp)
{
  guint *id = userp;

  if(id)
    g_source_remove(*id);

  /* -1 means we should just delete our timer. */
  if(timeout_ms == -1) {
    g_free(id);
    id = NULL;
  }
  else {
    if(!id)
      id = g_new(guint, 1);
    *id = g_timeout_add(timeout_ms, timeout_cb, id);
  }
  curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id);
  return 0;
}

curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);

⭐ AVAILABILITY ⭐

Added in 7.16.0 👑

💜 RETURN VALUE 💜

Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. periodt. 💅

🌸 SEE ALSO 🌸

• CURLMOPT_TIMERDATA(3)
• CURLMOPT_SOCKETFUNCTION(3)

---

okay that's the whole page, mwah 💋 — this cutie came from libcurl 7.37.0, dated 17 Jun 2014. slay. 🫶