MID.md (3268B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 # Multi Identifiers (mid) 8 9 All transfers (easy handles) added to a multi handle are assigned 10 a unique identifier until they are removed again. The multi handle 11 keeps a table `multi->xfers` that allow O(1) access to the easy 12 handle by its `mid`. 13 14 References to other easy handles *should* keep their `mid`s instead 15 of a pointer (not all code has been converted as of now). This solves 16 problems in easy and multi handle life cycle management as well as 17 iterating over handles where operations may add/remove other handles. 18 19 ### Values and Lifetime 20 21 An `mid` is an `unsigned int`. There are two reserved values: 22 23 * `0`: is the `mid` of an internal "admin" handle. Multi and share handles 24 each have their own admin handle for maintenance operations, like 25 shutting down connections. 26 * `UINT_MAX`: the "invalid" `mid`. Easy handles are initialized with 27 this value. They get it assigned again when removed from 28 a multi handle. 29 30 This makes potential range of `mid`s from `1` to `UINT_MAX - 1` *inside 31 the same multi handle at the same time*. However, the `multi->xfers` table 32 reuses `mid` values from previous transfers that have been removed. 33 34 `multi->xfers` is created with an initial capacity. At the time of this 35 writing that is `16` for "multi_easy" handles (used in `curl_easy_perform()` 36 and `512` for multi handles created with `curl_multi_init()`. 37 38 The first added easy handle gets `mid == 1` assigned. The second one receives `2`, 39 even when the fist one has been removed already. Every added handle gets an 40 `mid` one larger than the previously assigned one. Until the capacity of 41 the table is reached and it starts looking for a free id at `1` again (`0` 42 is always in the table). 43 44 When adding a new handle, the multi checks the amount of free entries 45 in the `multi->xfers` table. If that drops below a threshold (currently 25%), 46 the table is resized. This serves two purposes: one, a previous `mid` is not 47 reused immediately and second, table resizes are not needed that often. 48 49 The table is implemented in `uint-table.[ch]`. More details in [`UINT_SETS`](UINT_SETS.md). 50 51 ### Tracking `mid`s 52 53 There are several places where transfers need to be tracked: 54 55 * the multi tracks `process`, `pending` and `msgsent` transfers. A transfer 56 is in at most one of these at a time. 57 * connections track the transfers that are *attached* to them. 58 * multi event handling tracks transfers interested in a specific socket. 59 * DoH handles track the handle they perform lookups for (and vice versa). 60 61 There are two bitset implemented for storing `mid`s: `uint_bset` and `uint_spbset`. 62 The first is a bitset optimal for storing a large number of unsigned int values. 63 The second one is a "sparse" variant good for storing a small set of numbers. 64 More details about these in [`UINT_SETS`](UINT_SETS.md). 65 66 A multi uses `uint_bset`s for `process`, `pending` and `msgsent`. Connections 67 and sockets use the sparse variant as both often track only a single transfer 68 and at most 100 on an HTTP/2 or HTTP/3 connection/socket. 69 70 These sets allow safe iteration while being modified. This allows a multi 71 to iterate over its "process" set while existing transfers are removed 72 or new ones added.