From f3c35e371cc70f1b6bc33f7faa904d37d1567eb3 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sun, 17 Nov 2019 15:12:15 +0100 Subject: multi: add curl_multi_wakeup() This commit adds curl_multi_wakeup() which was previously in the TODO list under the curl_multi_unblock name. On some platforms and with some configurations this feature might not be available or can fail, in these cases a new error code (CURLM_WAKEUP_FAILURE) is returned from curl_multi_wakeup(). Fixes #4418 Closes #4608 --- docs/TODO | 8 ------- docs/libcurl/Makefile.inc | 1 + docs/libcurl/curl_multi_poll.3 | 11 ++++++++-- docs/libcurl/curl_multi_wakeup.3 | 47 ++++++++++++++++++++++++++++++++++++++++ docs/libcurl/libcurl-errors.3 | 2 ++ docs/libcurl/symbols-in-versions | 1 + 6 files changed, 60 insertions(+), 10 deletions(-) create mode 100644 docs/libcurl/curl_multi_wakeup.3 (limited to 'docs') diff --git a/docs/TODO b/docs/TODO index 46b015c02..e75c1647b 100644 --- a/docs/TODO +++ b/docs/TODO @@ -51,7 +51,6 @@ 2.4 Split connect and authentication process 2.5 Edge-triggered sockets should work 2.6 multi upkeep - 2.7 curl_multi_unblock 3. Documentation 3.2 Provide cmake config-file @@ -448,13 +447,6 @@ See https://github.com/curl/curl/issues/3199 -2.7 curl_multi_unblock - - A portable way to unblock curl_multi_wait from another thread. - - See https://github.com/curl/curl/issues/4418 and - https://github.com/curl/curl/wiki/curl_multi_unblock - 3. Documentation 3.2 Provide cmake config-file diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc index bd88c9c38..e1185e729 100644 --- a/docs/libcurl/Makefile.inc +++ b/docs/libcurl/Makefile.inc @@ -54,6 +54,7 @@ man_MANS = \ curl_multi_socket_all.3 \ curl_multi_strerror.3 \ curl_multi_timeout.3 \ + curl_multi_wakeup.3 \ curl_multi_wait.3 \ curl_share_cleanup.3 \ curl_share_init.3 \ diff --git a/docs/libcurl/curl_multi_poll.3 b/docs/libcurl/curl_multi_poll.3 index 9fc72c55d..bde80447a 100644 --- a/docs/libcurl/curl_multi_poll.3 +++ b/docs/libcurl/curl_multi_poll.3 @@ -48,10 +48,16 @@ total number of file descriptors on which interesting events occurred. This number can include both libcurl internal descriptors as well as descriptors provided in \fIextra_fds\fP. +The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to +wake up this function and return faster. This is one of the details +that makes this function different than \fIcurl_multi_wait(3)\fP which cannot +be woken up this way. + If no extra file descriptors are provided and libcurl has no file descriptor to offer to wait for, this function will instead wait during \fItimeout_ms\fP milliseconds (or shorter if an internal timer indicates so). This is the -detail that makes this function different than \fIcurl_multi_wait(3)\fP. +other detail that makes this function different than +\fIcurl_multi_wait(3)\fP. This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem @@ -107,4 +113,5 @@ CURLMcode type, general libcurl multi interface error code. See .SH AVAILABILITY This function was added in libcurl 7.66.0. .SH "SEE ALSO" -.BR curl_multi_fdset "(3), " curl_multi_perform "(3), " curl_multi_wait "(3)" +.BR curl_multi_fdset "(3), " curl_multi_perform "(3), " +.BR curl_multi_wait "(3), " curl_multi_wakeup "(3)" diff --git a/docs/libcurl/curl_multi_wakeup.3 b/docs/libcurl/curl_multi_wakeup.3 new file mode 100644 index 000000000..01b462f2f --- /dev/null +++ b/docs/libcurl/curl_multi_wakeup.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_multi_wakeup 3 "17 Nov 2019" "libcurl 7.68.0" "libcurl Manual" +.SH NAME +curl_multi_wakeup - wakes up a sleeping curl_multi_poll call +.SH SYNOPSIS +#include + +CURLMcode curl_multi_wakeup(CURLM *multi_handle); +.ad +.SH DESCRIPTION +This function can be called from any thread and it wakes up a +sleeping \fIcurl_multi_poll(3)\fP call that is currently (or will be) +waiting for activity or a timeout. + +If the function is called when there is no \fIcurl_multi_poll(3)\fP call, +it will cause the next call to return immediately. + +Calling this function only guarantees to wake up the current (or the next +if there is no current) \fIcurl_multi_poll(3)\fP call, which means it is +possible that multiple calls to this function will wake up the same waiting +operation. + +This function has no effect on \fIcurl_multi_wait(3)\fP calls. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_poll "(3), " curl_multi_wait "(3)" diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 1f985da8e..0305af43e 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -297,6 +297,8 @@ An easy handle already added to a multi handle was attempted to get added a second time. (Added in 7.32.1) .IP "CURLM_RECURSIVE_API_CALL (8)" An API function was called from inside a callback. +.IP "CURLM_WAKEUP_FAILURE (9)" +Wakeup is unavailable or failed. .SH "CURLSHcode" The "share" interface will return a CURLSHcode to indicate when an error has occurred. Also consider \fIcurl_share_strerror(3)\fP. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index f3131d2a2..d82439a5b 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -342,6 +342,7 @@ CURLM_INTERNAL_ERROR 7.9.6 CURLM_OK 7.9.6 CURLM_OUT_OF_MEMORY 7.9.6 CURLM_RECURSIVE_API_CALL 7.59.0 +CURLM_WAKEUP_FAILURE 7.68.0 CURLM_UNKNOWN_OPTION 7.15.4 CURLOPTTYPE_FUNCTIONPOINT 7.1 CURLOPTTYPE_LONG 7.1 -- cgit v1.2.3