generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

CURLMOPT_TIMERFUNCTION.3: Clarify, add an example

Browse Source
This commit is contained in:
Michael Stapelberg 2015-04-11 22:28:10 +02:00 committed by Daniel Stenberg
parent 3a87bdebd1
commit cc0e7ebc3b
1 changed files with 47 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
View File

@ -36,14 +36,21 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callbac
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function will be called when the timeout value changes. The
\fBtimeout_ms\fP value is at what latest time the application should call one
of the \&"performing" functions of the multi interface
(\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow
libcurl to keep timeouts and retries etc to work. A \fBtimeout_ms\fP value of
-1 means that there is no timeout at all, and 0 means that the timeout is
already expired. libcurl attempts to limit calling this only when the fixed
future timeout time actually changes.
Certain features, such as timeouts and retries, require you to call libcurl
even when there is no activity on the file descriptors.
Your callback function \fBtimer_callback\fP should install a non-repeating
timer with an interval of \fBtimeout_ms\fP. Each time that timer fires, call
either \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP,
depending on which interface you use.
A \fBtimeout_ms\fP value of -1 means you should delete your timer.
A \fBtimeout_ms\fP value of 0 means you should call
\fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP (once) as soon
as possible.
\fBtimer_callback\fP will only be called when the \fBtimeout_ms\fP changes.
The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.
@ -54,7 +61,38 @@ NULL
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
static gboolean timeout_cb(gpointer user_data) {
if (user_data) {
g_free(user_data);
curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
}
int running;
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);
.fi
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE