quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

curl_multi_poll.md (4036B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: curl_multi_poll
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - curl_multi_fdset (3)
      9   - curl_multi_perform (3)
     10   - curl_multi_wait (3)
     11   - curl_multi_wakeup (3)
     12 Protocol:
     13   - All
     14 Added-in: 7.66.0
     15 ---
     16 
     17 # NAME
     18 
     19 curl_multi_poll - poll on all easy handles in a multi handle
     20 
     21 # SYNOPSIS
     22 
     23 ~~~c
     24 #include <curl/curl.h>
     25 
     26 CURLMcode curl_multi_poll(CURLM *multi_handle,
     27                           struct curl_waitfd extra_fds[],
     28                           unsigned int extra_nfds,
     29                           int timeout_ms,
     30                           int *numfds);
     31 ~~~
     32 
     33 # DESCRIPTION
     34 
     35 curl_multi_poll(3) polls all file descriptors used by the curl easy
     36 handles contained in the given multi handle set. It blocks until activity is
     37 detected on at least one of the handles or *timeout_ms* has passed.
     38 Alternatively, if the multi handle has a pending internal timeout that has a
     39 shorter expiry time than *timeout_ms*, that shorter time is used instead
     40 to make sure timeout accuracy is reasonably kept.
     41 
     42 The calling application may pass additional curl_waitfd structures which are
     43 similar to *poll(2)*'s *pollfd* structure to be waited on in the same
     44 call.
     45 
     46 On completion, if *numfds* is non-NULL, it gets populated with the total
     47 number of file descriptors on which interesting events occurred. This number
     48 can include both libcurl internal descriptors as well as descriptors provided
     49 in *extra_fds*.
     50 
     51 The curl_multi_wakeup(3) function can be used from another thread to
     52 wake up this function and return faster. This is one of the details
     53 that makes this function different than curl_multi_wait(3) which cannot
     54 be woken up this way.
     55 
     56 If no extra file descriptors are provided and libcurl has no file descriptor
     57 to offer to wait for, this function instead waits during *timeout_ms*
     58 milliseconds (or shorter if an internal timer indicates so). This is the other
     59 detail that makes this function different than curl_multi_wait(3).
     60 
     61 This function is encouraged to be used instead of select(3) when using the
     62 multi interface to allow applications to easier circumvent the common problem
     63 with 1024 maximum file descriptors.
     64 
     65 # curl_waitfd
     66 
     67 ~~~c
     68 struct curl_waitfd {
     69   curl_socket_t fd;
     70   short events;
     71   short revents;
     72 };
     73 ~~~
     74 
     75 ## CURL_WAIT_POLLIN
     76 
     77 Bit flag to curl_waitfd.events indicating the socket should poll on read
     78 events such as new data received.
     79 
     80 ## CURL_WAIT_POLLPRI
     81 
     82 Bit flag to curl_waitfd.events indicating the socket should poll on high
     83 priority read events such as out of band data.
     84 
     85 ## CURL_WAIT_POLLOUT
     86 
     87 Bit flag to curl_waitfd.events indicating the socket should poll on write
     88 events such as the socket being clear to write without blocking.
     89 
     90 # %PROTOCOLS%
     91 
     92 # EXAMPLE
     93 
     94 ~~~c
     95 extern void handle_fd(int);
     96 
     97 int main(void)
     98 {
     99   CURL *easy_handle;
    100   CURLM *multi_handle;
    101   int still_running = 0;
    102   int myfd = 2; /* this is our own file descriptor */
    103 
    104   multi_handle = curl_multi_init();
    105   easy_handle = curl_easy_init();
    106 
    107   /* add the individual easy handle */
    108   curl_multi_add_handle(multi_handle, easy_handle);
    109 
    110   do {
    111     CURLMcode mc;
    112     int numfds;
    113 
    114     mc = curl_multi_perform(multi_handle, &still_running);
    115 
    116     if(mc == CURLM_OK) {
    117       struct curl_waitfd myown;
    118       myown.fd = myfd;
    119       myown.events = CURL_WAIT_POLLIN; /* wait for input */
    120       myown.revents = 0; /* clear it */
    121 
    122       /* wait for activity on curl's descriptors or on our own,
    123          or timeout */
    124       mc = curl_multi_poll(multi_handle, &myown, 1, 1000, &numfds);
    125 
    126       if(myown.revents) {
    127         /* did our descriptor receive an event? */
    128         handle_fd(myfd);
    129       }
    130     }
    131 
    132     if(mc != CURLM_OK) {
    133       fprintf(stderr, "curl_multi failed, code %d.\n", mc);
    134       break;
    135     }
    136 
    137   } while(still_running);
    138 
    139   curl_multi_remove_handle(multi_handle, easy_handle);
    140 }
    141 ~~~
    142 
    143 # %AVAILABILITY%
    144 
    145 # RETURN VALUE
    146 
    147 This function returns a CURLMcode indicating success or error.
    148 
    149 CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
    150 libcurl-errors(3).