Expand/Shrink

curl_multi_wait

Definition: include builtins\libcurl.e

{CURLMcode curlmcode, integer numfds} = curl_multi_wait(atom mcurl, atom p_extra_fds, integer nextra_fds, integer timeout_ms)
Description: Polls on all easy handles in a multi handle.

curl_multi_wait polls all file descriptors used by the curl easy handles contained in the given multi handle set.
It will block until activity is detected on at least one of the handles or timeout_ms has passed.
Alternatively, if the multi handle has a pending internal timeout that has a shorter expiry time than timeout_ms, that shorter time will be used instead to make sure timeout accuracy is reasonably kept.

The calling application may pass additional curl_waitfd structures which are similar to poll(2)’s pollfd structure to be waited on in the same call.

On completion it also returns the total number of file descriptors on which interesting events occurred.
This number can include both libcurl internal descriptors as well as descriptors provided in extra_fds.

If no extra file descriptors are provided and libcurl has no file descriptor to offer to wait for, this function will return immediately.

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 with 1024 maximum file descriptors.

The curl_waitfd structure is defined as follows (if in use, p_extra_fds should be allocated and initialised memory of this size, times nextra_fds): 

struct curl_waitfd {
  curl_socket_t fd;
  short events;
  short revents;
};

and the following bit flags apply to curl_waitfd.events:

CURL_WAIT_POLLIN: indicates the socket should poll on read events such as new data received.
CURL_WAIT_POLLPRI: indicates the socket should poll on high priority read events such as out of band data.
CURL_WAIT_POLLOUT: indicates the socket should poll on write events such as the socket being clear to write without blocking.

Return value: CURLMcode type, general libcurl multi interface error code.

Availability: This function was added in libcurl 7.28.0.
pwa/p2js: Not supported.
Example:
Copy 
-- (This is not a complete runnable example)

atom easy_handle
atom multi_handle
 
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle)
 
while 1 do
    CURLMcode mc
    integer still_running, numfds, repeats=0
 
    {mc,still_running} = curl_multi_perform(multi_handle)

    -- DEV/SUG: if still_running!=was_still_running then ??? end if
    
    if still_running=0 then exit end if
 
    if mc=CURLM_OK then
        /* wait for activity, timeout or "nothing" */
        {mc,numfds} = curl_multi_wait(multi_handle, NULL, 0, 1000)
    end if
 
    if mc!=CURLM_OK then
        printf(2, "curl_multi failed, code %d.n", {mc})
        exit
    end if
 
    --
    -- numfds being zero means either a timeout or no file descriptors to wait for. 
    -- Try timeout on first occurrence, then assume no file descriptors and no file 
    -- descriptors to wait for means wait for 100 milliseconds.
    --
    if numfds=0 then
        repeats += 1 /* count number of repeated zero numfds */
        if repeats>1 then
            sleep(0.1) /* sleep 100 milliseconds */
        end if
    else
        repeats = 0
    end if
end while
 
curl_multi_remove_handle(multi_handle, easy_handle)
See Also: See also: curl_multi_fdset, ??, curl_multi_perform