Artifactspublic-v0

curl

master
ply4 git calls310 ms289 KiB2 cachedprotocol v2
135 lines3.8 KiBRaw

NAME

CURLMOPT_NOTIFYFUNCTION - callback receiving notifications

SYNOPSIS

c
#include <curl/curl.h>

void notify_callback(CURLM *multi,     /* multi handle */
                     unsigned int notification, /* notification type */
                     CURL *easy,       /* easy handle */
                     void *notifyp);   /* private notify pointer */

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_NOTIFYFUNCTION, notify_callback);

DESCRIPTION

Pass a pointer to your callback function, which should match the prototype shown above.

When the multi handle processes transfers, changes can be observed by receiving notifications about them. This can eliminate the need to constantly interrogate the multi handle to observe such changes to act on them.

Notifications are collected and dispatched to the application's callback function at an appropriate time.

The notify callback is different from other callbacks in that it can use more libcurl API functions. Apart from curl_multi_perform(3), curl_multi_socket(3), curl_multi_socket_action(3), curl_multi_socket_all(3) and curl_multi_cleanup(3) it may call all other methods on the multi and easy handles. This includes adding and removing easy handles to/from the multi handle.

Internal handles are owned by libcurl and the public API rejects them: the easy interface functions fail with CURLE_BAD_FUNCTION_ARGUMENT, and curl_multi_add_handle(3) and curl_multi_remove_handle(3) return CURLM_BAD_EASY_HANDLE.

This callback may get invoked at any time when interacting with libcurl. This may even happen after all transfers are done and may also happen during a call to curl_multi_cleanup(3) when cached connections are shut down.

CALLBACK ARGUMENTS

multi identifies the multi handle that triggered the notification.

notification is the type of notification, e.g. what happened. The following types are available right now. In the future, new ones might be added.

CURLMNOTIFY_INFO_READ

When enabled via curl_multi_notify_enable(3), this informs the application that there are new messages to be processed via curl_multi_info_read(3).

This notification happens whenever a message is added to an empty message stack in the multi handle and not for subsequent additions. The notification callback is then expected to read all available message, emptying the stack, so a subsequent addition triggers the notification again.

The easy handle passed is an internal handle.

CURLMNOTIFY_EASY_DONE

When enabled via curl_multi_notify_enable(3), this notification is triggered when an easy handle has finished. This happens both for successful and failed transfers.

The easy handle passed is the transfer that is done. This may be an internal handle when DoH or other features are used.

easy identifies the transfer involved. This may be one of the application's own easy handle or an internal handle.

notifyp is set with CURLMOPT_NOTIFYDATA(3).

DEFAULT

NULL (no callback)

%PROTOCOLS%

EXAMPLE

c
struct priv {
  void *ours;
};

static void notify_cb(CURLM *multi, unsigned int notification,
                      CURL *easy, void *notifyp)
{
  struct priv *p = notifyp;
  printf("my ptr: %p\n", p->ours);
  /* ... */
}

int main(void)
{
  struct priv setup;
  CURLM *multi = curl_multi_init();
  /* ... use socket callback and custom pointer */
  curl_multi_setopt(multi, CURLMOPT_NOTIFYFUNCTION, notify_cb);
  curl_multi_setopt(multi, CURLMOPT_NOTIFYDATA, &setup);
  curl_multi_notify_enable(multi, CURLMNOTIFY_INFO_READ);
}

%AVAILABILITY%

RETURN VALUE

Returns CURLM_OK.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLMOPT_NOTIFYFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLMOPT_NOTIFYDATA (3)
9 - curl_multi_socket_action (3)
10 - curl_multi_notify_disable (3)
11 - curl_multi_notify_enable (3)
12Protocol:
13 - All
14Added-in: 8.17.0
15---
17# NAME
19CURLMOPT_NOTIFYFUNCTION - callback receiving notifications
21# SYNOPSIS
23~~~c
24#include <curl/curl.h>
26void notify_callback(CURLM *multi, /* multi handle */
27 unsigned int notification, /* notification type */
28 CURL *easy, /* easy handle */
29 void *notifyp); /* private notify pointer */
31CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_NOTIFYFUNCTION, notify_callback);
32~~~
34# DESCRIPTION
36Pass a pointer to your callback function, which should match the prototype
37shown above.
39When the multi handle processes transfers, changes can be observed
40by receiving notifications about them. This can eliminate the need to
41constantly interrogate the multi handle to observe such changes to
42act on them.
44Notifications are collected and dispatched to the application's callback
45function at an appropriate time.
47The notify callback is different from other callbacks in that it
48can use more libcurl API functions. Apart from curl_multi_perform(3),
49curl_multi_socket(3), curl_multi_socket_action(3), curl_multi_socket_all(3)
50and curl_multi_cleanup(3) it may call all other methods on the
51multi and easy handles. This includes adding and removing easy
52handles to/from the multi handle.
54Internal handles are owned by libcurl and the public API rejects them: the
55easy interface functions fail with CURLE_BAD_FUNCTION_ARGUMENT, and
56curl_multi_add_handle(3) and curl_multi_remove_handle(3) return
57CURLM_BAD_EASY_HANDLE.
59This callback may get invoked at any time when interacting with libcurl.
60This may even happen after all transfers are done and *may also*
61happen *during* a call to curl_multi_cleanup(3) when cached connections
62are shut down.
64# CALLBACK ARGUMENTS
66*multi* identifies the multi handle that triggered the notification.
68**notification** is the type of notification, e.g. what happened. The
69following types are available right now. In the future, new ones might be
70added.
72## CURLMNOTIFY_INFO_READ
74When enabled via curl_multi_notify_enable(3), this informs the application
75that there are new messages to be processed via curl_multi_info_read(3).
77This notification happens whenever a message is added to an empty
78message stack in the multi handle and not for subsequent additions. The
79notification callback is then expected to read all available message,
80emptying the stack, so a subsequent addition triggers the notification
81again.
83The *easy* handle passed is an internal handle.
85## CURLMNOTIFY_EASY_DONE
87When enabled via curl_multi_notify_enable(3), this notification is triggered
88when an easy handle has finished. This happens both for successful and failed
89transfers.
91The *easy* handle passed is the transfer that is done. This *may* be
92an internal handle when DoH or other features are used.
94*easy* identifies the transfer involved. This may be one of the
95application's own easy handle or an internal handle.
97**notifyp** is set with CURLMOPT_NOTIFYDATA(3).
99# DEFAULT
101NULL (no callback)
103# %PROTOCOLS%
105# EXAMPLE
107~~~c
108struct priv {
109 void *ours;
110};
112static void notify_cb(CURLM *multi, unsigned int notification,
113 CURL *easy, void *notifyp)
115 struct priv *p = notifyp;
116 printf("my ptr: %p\n", p->ours);
117 /* ... */
120int main(void)
122 struct priv setup;
123 CURLM *multi = curl_multi_init();
124 /* ... use socket callback and custom pointer */
125 curl_multi_setopt(multi, CURLMOPT_NOTIFYFUNCTION, notify_cb);
126 curl_multi_setopt(multi, CURLMOPT_NOTIFYDATA, &setup);
127 curl_multi_notify_enable(multi, CURLMNOTIFY_INFO_READ);
129~~~
131# %AVAILABILITY%
133# RETURN VALUE
135Returns CURLM_OK.
Diagnostics4 git calls · 310 ms
CallStatusSizeTime0310 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
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 · hit5 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
fetch2001.7 KiB302 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=302
git.response.bytes=1752
git.response.cache=MISS
git.response.duration_ms=302
git.fetch.wants=cd57682c24afa593130de6434ef3d217ecdc31dc
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=1752
git.pkt.payload.max=1731
git.sideband.band1.bytes=1730
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
a5e342072a8e6e2a
Request
76f20cae…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format