Artifactspublic-v0

curl

master
ply4 git calls26 ms289 KiB3 cachedprotocol v2
127 lines4.5 KiBRaw

NAME

curl_multi_socket_action - read/write available data given an action

SYNOPSIS

c
#include <curl/curl.h>

CURLMcode curl_multi_socket_action(CURLM *multi_handle,
                                   curl_socket_t sockfd,
                                   int ev_bitmask,
                                   int *running_handles);

DESCRIPTION

When the application has detected action on a socket handled by libcurl, it should call curl_multi_socket_action(3) with the sockfd argument set to the socket with the action. When the events on a socket are known, they can be passed as an events bitmask ev_bitmask by first setting ev_bitmask to 0, and then adding using bitwise OR (|) any combination of events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and libcurl tests the descriptor internally. It is also permissible to pass CURL_SOCKET_TIMEOUT to the sockfd parameter in order to initiate the whole process or when a timeout occurs.

At return, running_handles points to the number of running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. When you call curl_multi_socket_action(3) on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use curl_multi_info_read(3) to figure out which easy handle that completed.

The curl_multi_socket_action(3) function informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They update the status with changes since the previous time the callback was called.

Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option with curl_multi_setopt(3). Your application then gets called with information on how long to wait for socket actions at most before doing the timeout action: call the curl_multi_socket_action(3) function with the sockfd argument set to CURL_SOCKET_TIMEOUT. You can also use the curl_multi_timeout(3) function to poll the value at any given time, but for an event-based system using the callback is far better than relying on polling the timeout value.

When this function returns error, the state of all transfers are uncertain and they cannot be continued. curl_multi_socket_action(3) should not be called again on the same multi handle after an error has been returned, unless first removing all the handles and adding new ones.

TYPICAL USAGE

  1. Create a multi handle

  2. Set the socket callback with CURLMOPT_SOCKETFUNCTION(3)

  3. Set the timeout callback with CURLMOPT_TIMERFUNCTION(3), to get to know what timeout value to use when waiting for socket activities.

  4. Add easy handles with curl_multi_add_handle()

  5. Provide some means to manage the sockets libcurl is using, so you can check them for activity. This can be done through your application code, or by way of an external library such as libevent or glib.

  6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) to kickstart everything. To get one or more callbacks called.

  7. Wait for activity on any of libcurl's sockets, use the timeout value your callback has been told.

  8. When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, call curl_multi_socket_action(3) with CURL_SOCKET_TIMEOUT.

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  /* the event-library gets told when there is activity on the socket 'fd',
     which we translate to a call to curl_multi_socket_action() */
  int running = 0;
  int fd = 3; /* the descriptor that had action */
  int bitmask = 2; /* what activity that happened */

  CURLM *multi = curl_multi_init();

  CURLMcode mresult = curl_multi_socket_action(multi, fd, bitmask, &running);
  if(mresult)
    printf("error: %s\n", curl_multi_strerror(mresult));
}

%AVAILABILITY%

RETURN VALUE

This function returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_multi_socket_action
5Section: 3
6Source: libcurl
7See-also:
8 - curl_multi_cleanup (3)
9 - curl_multi_fdset (3)
10 - curl_multi_info_read (3)
11 - curl_multi_init (3)
12 - the hiperfifo.c example
13Protocol:
14 - All
15Added-in: 7.16.3
16---
18# NAME
20curl_multi_socket_action - read/write available data given an action
22# SYNOPSIS
24~~~c
25#include <curl/curl.h>
27CURLMcode curl_multi_socket_action(CURLM *multi_handle,
28 curl_socket_t sockfd,
29 int ev_bitmask,
30 int *running_handles);
31~~~
33# DESCRIPTION
35When the application has detected action on a socket handled by libcurl, it
36should call curl_multi_socket_action(3) with the **sockfd** argument
37set to the socket with the action. When the events on a socket are known, they
38can be passed as an events bitmask **ev_bitmask** by first setting
39**ev_bitmask** to 0, and then adding using bitwise OR (|) any combination of
40events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
41CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
42libcurl tests the descriptor internally. It is also permissible to pass
43CURL_SOCKET_TIMEOUT to the **sockfd** parameter in order to initiate the
44whole process or when a timeout occurs.
46At return, **running_handles** points to the number of running easy handles
47within the multi handle. When this number reaches zero, all transfers are
48complete/done. When you call curl_multi_socket_action(3) on a specific
49socket and the counter decreases by one, it DOES NOT necessarily mean that
50this exact socket/transfer is the one that completed. Use
51curl_multi_info_read(3) to figure out which easy handle that completed.
53The curl_multi_socket_action(3) function informs the application about
54updates in the socket (file descriptor) status by doing none, one, or multiple
55calls to the socket callback function set with the
56CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
57update the status with changes since the previous time the callback was
58called.
60Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
61with curl_multi_setopt(3). Your application then gets called with
62information on how long to wait for socket actions at most before doing the
63timeout action: call the curl_multi_socket_action(3) function with the
64**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
65curl_multi_timeout(3) function to poll the value at any given time, but
66for an event-based system using the callback is far better than relying on
67polling the timeout value.
69When this function returns error, the state of all transfers are uncertain and
70they cannot be continued. curl_multi_socket_action(3) should not be
71called again on the same multi handle after an error has been returned, unless
72first removing all the handles and adding new ones.
74# TYPICAL USAGE
761. Create a multi handle
782. Set the socket callback with CURLMOPT_SOCKETFUNCTION(3)
803. Set the timeout callback with CURLMOPT_TIMERFUNCTION(3), to get to
81know what timeout value to use when waiting for socket activities.
834. Add easy handles with curl_multi_add_handle()
855. Provide some means to manage the sockets libcurl is using, so you can check
86them for activity. This can be done through your application code, or by way
87of an external library such as libevent or glib.
896. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
90to kickstart everything. To get one or more callbacks called.
927. Wait for activity on any of libcurl's sockets, use the timeout value your
93callback has been told.
958. When activity is detected, call curl_multi_socket_action() for the
96socket(s) that got action. If no activity is detected and the timeout expires,
97call curl_multi_socket_action(3) with *CURL_SOCKET_TIMEOUT*.
99# %PROTOCOLS%
101# EXAMPLE
103~~~c
104int main(void)
106 /* the event-library gets told when there is activity on the socket 'fd',
107 which we translate to a call to curl_multi_socket_action() */
108 int running = 0;
109 int fd = 3; /* the descriptor that had action */
110 int bitmask = 2; /* what activity that happened */
112 CURLM *multi = curl_multi_init();
114 CURLMcode mresult = curl_multi_socket_action(multi, fd, bitmask, &running);
115 if(mresult)
116 printf("error: %s\n", curl_multi_strerror(mresult));
118~~~
120# %AVAILABILITY%
122# RETURN VALUE
124This function returns a CURLMcode indicating success or error.
126CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
127libcurl-errors(3).
Diagnostics4 git calls · 26 ms
CallStatusSizeTime026 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.1 KiB · hit21 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=21
git.response.bytes=2100
git.response.cache=HIT
git.response.duration_ms=21
git.fetch.wants=4d690fd97d26d2cd16966a449955d76e6dbbbc9e
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2100
git.pkt.payload.max=2079
git.sideband.band1.bytes=2078
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e31aa02c6d3e6e
Request
22a64876…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format