Artifactspublic-v0

curl

master
ply4 git calls182 ms289 KiB2 cachedprotocol v2
112 lines4.1 KiBRaw

Thread Pool and Queue

The thread pool and queue manage asynchronous processing of "work items" to a user. The "work items" are opaque to the pool and queue, represented by a void *, handled via callback functions.

Thread pool and queue are available with pthreads or native Win32 builds.

Curl_thrdpool

This data structure manages a pool of threads for asynchronous operations.

Properties

A pool's properties are:

  • minimum number of threads running, default 0
  • maximum number of threads running
  • timeout for idle threads before they shut down

The minimum number of threads is started at creation of the pool and kept always running. On demand, when more work is available but all existing threads are busy, it starts new threads, up to maximum.

When work ceases, the threads "above" the minimum number exit again after the given idle time.

Operation

The pool is created with providing three callback functions:

  • take: the pool calls this to take a new "work item" for processing. From the pool's point of view, a work item is a void *. "take" is called from the pool's threads. When getting anything besides NULL, the thread is "busy". On getting NULL, the thread becomes idle.
  • process: called by a pool thread to process a work item. This can not return any error. Any error handling must be done via properties in the work item itself, opaque to the pool.
  • return: after processing, the work item is returned and the pool has no longer have any memory of it.

The pool only tries to "take" new work items when told to. Calling Curl_thrdpool_signal(pool, n) awakens up to nthreads which then take new work items. This may cause new threads being started. The other time a pool thread "take"s work it when it has finished processing and returned another item.

A thread pool can be destroyed via Curl_thrdpool_destroy(pool, join) where join determines if active threads shall be joined or detached.

Safety

The thread pool operates using a mutex and condition variables to manage concurrency. All interactions and callback invocation are done under the pool's mutex lock, except the "process" callback which is invoked unlocked.

To avoid deadlocks, no callback must invoke other pool functions. Also, any call of pool functions may result in callback invocations.

The "work items", once "taken" by the pool, should not be referenced from any other place. Thread pools always invoke the "return" callback on a work item, even after the pool has been destroyed by detaching the threads.

There is a user_data in the pool's creation that is passed to "take" and "return" callbacks. Once a pool is destroyed, this user_data is cleared and "return" callbacks always see a NULL. This way, the "return" callback may act on that fact.

Curl_thrdq

A thrdq is a two-way queue with a thread pool. Users of a thread queue may "send" work items into the queue and "receive" processed items back.

Properties

A queue's properties are:

  • The properties of the thread pool to create
  • the maximum length of the "send" queue, 0 for unlimited

Operation

The queue is created with providing three callback functions:

  • free: called to free a work item that is in the queue but is no longer returned (or processed). This happens when the queue is destroyed or when work items are removed for other reasons.
  • process: process the item. Can not fail.
  • event: called when work items have been added to the "receive" list.

Users of a thread queue call Curl_thrdq_send() to add a work item to the queue. Calling Curl_thrdq_recv() delivers processed items back.

Safety

The thread queue operates using a mutex and condition variables to manage concurrency. All interactions and callback invocation are done under the queue's mutex lock, except the "process" callback which is invoked unlocked.

Users of a thread queue should not hold any reference to work items sent into the queue. The provided "free" callback has to take care of any resources allocated by work items.

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# Thread Pool and Queue
9The thread pool and queue manage asynchronous processing of "work items"
10to a user. The "work items" are opaque to the pool and queue, represented
11by a `void *`, handled via callback functions.
13Thread pool and queue are available with `pthreads` or native Win32
14builds.
16## `Curl_thrdpool`
18This data structure manages a pool of threads for asynchronous operations.
20### Properties
22A pool's properties are:
24- minimum number of threads running, default 0
25- maximum number of threads running
26- timeout for idle threads before they shut down
28The minimum number of threads is started at creation of the pool and
29kept always running. On demand, when more work is available but all
30existing threads are busy, it starts new threads, up to maximum.
32When work ceases, the threads "above" the minimum number exit again
33after the given idle time.
35### Operation
37The pool is created with providing three callback functions:
39- `take`: the pool calls this to take a new "work item" for processing. From
40 the pool's point of view, a work item is a `void *`. "take" is called from
41 the pool's threads. When getting anything besides `NULL`, the thread is
42 "busy". On getting `NULL`, the thread becomes idle.
43- `process`: called by a pool thread to process a work item. This can not
44 return any error. Any error handling must be done via properties in
45 the work item itself, opaque to the pool.
46- `return`: after processing, the work item is returned and the pool has
47 no longer have any memory of it.
49The pool only tries to "take" new work items when told to. Calling
50`Curl_thrdpool_signal(pool, n)` awakens up to `n`threads which then
51take new work items. This may cause new threads being started. The other
52time a pool thread "take"s work it when it has finished
53processing and returned another item.
55A thread pool can be destroyed via `Curl_thrdpool_destroy(pool, join)` where
56`join` determines if active threads shall be joined or detached.
58### Safety
60The thread pool operates using a mutex and condition variables to manage
61concurrency. All interactions and callback invocation are done under
62the pool's mutex lock, *except* the "process" callback which is invoked
63unlocked.
65To avoid deadlocks, no callback must invoke other pool functions. Also,
66any call of pool functions may result in callback invocations.
68The "work items", once "taken" by the pool, should not be referenced
69from any other place. Thread pools **always** invoke the "return"
70callback on a work item, even after the pool has been destroyed by
71detaching the threads.
73There is a `user_data` in the pool's creation that is passed to "take"
74and "return" callbacks. Once a pool is destroyed, this `user_data` is
75cleared and "return" callbacks always see a `NULL`. This way,
76the "return" callback may act on that fact.
78## `Curl_thrdq`
80A `thrdq` is a two-way queue with a thread pool. Users of a thread queue may
81"send" work items into the queue and "receive" processed items back.
83### Properties
85A queue's properties are:
87- The properties of the thread pool to create
88- the maximum length of the "send" queue, 0 for unlimited
90### Operation
92The queue is created with providing three callback functions:
94- `free`: called to free a work item that is in the queue but is
95 no longer returned (or processed). This happens when the queue is
96 destroyed or when work items are removed for other reasons.
97- `process`: process the item. Can not fail.
98- `event`: called when work items have been added to the "receive" list.
100Users of a thread queue call `Curl_thrdq_send()` to add a work item to
101the queue. Calling `Curl_thrdq_recv()` delivers processed items back.
103### Safety
105The thread queue operates using a mutex and condition variables to manage
106concurrency. All interactions and callback invocation are done under
107the queue's mutex lock, *except* the "process" callback which is invoked
108unlocked.
110Users of a thread queue should not hold any reference to work items sent
111into the queue. The provided "free" callback has to take care of any
112resources allocated by work items.
Diagnostics4 git calls · 182 ms
CallStatusSizeTime0182 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
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 · 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=177
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 KiB177 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1735
git.response.cache=MISS
git.response.duration_ms=177
git.fetch.wants=65a2f70dc544ffe31bdf01fbdb6c4f76f032655c
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=1735
git.pkt.payload.max=1714
git.sideband.band1.bytes=1713
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
a5e32534c94298f1
Request
898dfd29…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format