Artifactspublic-v0

curl

master
ply4 git calls77 ms289 KiB3 cachedprotocol v2
195 lines5.3 KiBRaw

llist - linked lists

#include "llist.h"

This is the internal module for linked lists. The API is designed to be flexible but also to avoid dynamic memory allocation.

None of the involved structs should be accessed using struct fields (outside of llist.c). Use the functions.

Setup and shutdown

struct Curl_llist is the struct holding a single linked list. It needs to be initialized with a call to Curl_llist_init() before it can be used

To clean up a list, call Curl_llist_destroy(). Since the linked lists themselves do not allocate memory, it can also be fine to not clean up the list.

Add a node

There are two functions for adding a node to a linked list:

  1. Add it last in the list with Curl_llist_append
  2. Add it after a specific existing node with llist_insert_next

When a node is added to a list, it stores an associated custom pointer to anything you like and you provide a pointer to a struct Curl_llist_node struct in which it stores and updates pointers. If you intend to add the same struct to multiple lists concurrently, you need to have one struct Curl_llist_node for each list.

Add a node to a list with Curl_llist_append(list, elem, node). Where

  • list: points to a struct Curl_llist
  • elem: points to what you want added to the list
  • node: is a pointer to a struct Curl_llist_node. Data storage for this node.

Example: to add a struct foobar to a linked list. Add a node struct within it:

struct foobar {
  char *random;
  struct Curl_llist_node storage; /* can be anywhere in the struct */
  char *data;
};

struct Curl_llist barlist; /* the list for foobar entries */
struct foobar entries[10];

Curl_llist_init(&barlist, NULL);

/* add the first struct to the list */
Curl_llist_append(&barlist, &entries[0], &entries[0].storage);

See also llist_insert_next.

Remove a node

Remove a node again from a list by calling Curl_llist_remove(). This destroys the node's elem (e.g. calling a registered free function).

To remove a node without destroying its elem, use Curl_node_take_elem() which returns the elem pointer and removes the node from the list. The caller then owns this pointer and has to take care of it.

Iterate

To iterate over a list: first get the head entry and then iterate over the nodes as long there is a next. Each node has an element associated with it, the custom pointer you stored there. Usually a struct pointer or similar.

struct Curl_llist_node *iter;

/* get the first entry of the 'barlist' */
iter = Curl_llist_head(&barlist);

while(iter) {
  /* extract the element pointer from the node */
  struct foobar *elem = Curl_node_elem(iter);

  /* advance to the next node in the list */
  iter = Curl_node_next(iter);
}

Function overview

Curl_llist_init

c
void Curl_llist_init(struct Curl_llist *list, Curl_llist_dtor dtor);

Initializes the list. The argument dtor is NULL or a function pointer that gets called when list nodes are removed from this list.

The function is infallible.

c
typedef void (*Curl_llist_dtor)(void *user, void *elem);

dtor is called with two arguments: user and elem. The first being the user pointer passed in to Curl_llist_remove()or Curl_llist_destroy() and the second is the elem pointer associated with removed node. The pointer that Curl_node_elem() would have returned for that node.

Curl_llist_destroy

c
void Curl_llist_destroy(struct Curl_llist *list, void *user);

This removes all nodes from the list. This leaves the list in a cleared state.

The function is infallible.

Curl_llist_append

c
void Curl_llist_append(struct Curl_llist *list,
                       const void *elem, struct Curl_llist_node *node);

Adds node last in the list with a custom pointer to elem.

The function is infallible.

llist_insert_next

c
void llist_insert_next(struct Curl_llist *list,
                       struct Curl_llist_node *before,
                       const void *elem,
                       struct Curl_llist_node *node);

Adds node to the list with a custom pointer to elem immediately after the previous list before.

The function is infallible.

Curl_llist_head

c
struct Curl_llist_node *Curl_llist_head(struct Curl_llist *list);

Returns a pointer to the first node of the list, or a NULL if empty.

Curl_node_uremove

c
void Curl_node_uremove(struct Curl_llist_node *node, void *user);

Removes the node the list it was previously added to. Passes the user pointer to the list's destructor function if one was setup.

The function is infallible.

Curl_node_remove

c
void Curl_node_remove(struct Curl_llist_node *node);

Removes the node the list it was previously added to. Passes a NULL pointer to the list's destructor function if one was setup.

The function is infallible.

Curl_node_elem

c
void *Curl_node_elem(struct Curl_llist_node *node);

Given a list node, this function returns the associated element.

Curl_node_next

c
struct Curl_llist_node *Curl_node_next(struct Curl_llist_node *node);

Given a list node, this function returns the next node in the list.

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# `llist` - linked lists
9 #include "llist.h"
11This is the internal module for linked lists. The API is designed to be
12flexible but also to avoid dynamic memory allocation.
14None of the involved structs should be accessed using struct fields (outside
15of `llist.c`). Use the functions.
17## Setup and shutdown
19`struct Curl_llist` is the struct holding a single linked list. It needs to be
20initialized with a call to `Curl_llist_init()` before it can be used
22To clean up a list, call `Curl_llist_destroy()`. Since the linked lists
23themselves do not allocate memory, it can also be fine to *not* clean up the
24list.
26## Add a node
28There are two functions for adding a node to a linked list:
301. Add it last in the list with `Curl_llist_append`
312. Add it after a specific existing node with `llist_insert_next`
33When a node is added to a list, it stores an associated custom pointer to
34anything you like and you provide a pointer to a `struct Curl_llist_node`
35struct in which it stores and updates pointers. If you intend to add the same
36struct to multiple lists concurrently, you need to have one `struct
37Curl_llist_node` for each list.
39Add a node to a list with `Curl_llist_append(list, elem, node)`. Where
41- `list`: points to a `struct Curl_llist`
42- `elem`: points to what you want added to the list
43- `node`: is a pointer to a `struct Curl_llist_node`. Data storage for this
44 node.
46Example: to add a `struct foobar` to a linked list. Add a node struct within
47it:
49 struct foobar {
50 char *random;
51 struct Curl_llist_node storage; /* can be anywhere in the struct */
52 char *data;
53 };
55 struct Curl_llist barlist; /* the list for foobar entries */
56 struct foobar entries[10];
58 Curl_llist_init(&barlist, NULL);
60 /* add the first struct to the list */
61 Curl_llist_append(&barlist, &entries[0], &entries[0].storage);
63See also `llist_insert_next`.
65## Remove a node
67Remove a node again from a list by calling `Curl_llist_remove()`. This
68destroys the node's `elem` (e.g. calling a registered free function).
70To remove a node without destroying its `elem`, use `Curl_node_take_elem()`
71which returns the `elem` pointer and removes the node from the list. The
72caller then owns this pointer and has to take care of it.
74## Iterate
76To iterate over a list: first get the head entry and then iterate over the
77nodes as long there is a next. Each node has an *element* associated with it,
78the custom pointer you stored there. Usually a struct pointer or similar.
80 struct Curl_llist_node *iter;
82 /* get the first entry of the 'barlist' */
83 iter = Curl_llist_head(&barlist);
85 while(iter) {
86 /* extract the element pointer from the node */
87 struct foobar *elem = Curl_node_elem(iter);
89 /* advance to the next node in the list */
90 iter = Curl_node_next(iter);
91 }
93# Function overview
95## `Curl_llist_init`
97~~~c
98void Curl_llist_init(struct Curl_llist *list, Curl_llist_dtor dtor);
99~~~
101Initializes the `list`. The argument `dtor` is NULL or a function pointer that
102gets called when list nodes are removed from this list.
104The function is infallible.
106~~~c
107typedef void (*Curl_llist_dtor)(void *user, void *elem);
108~~~
110`dtor` is called with two arguments: `user` and `elem`. The first being the
111`user` pointer passed in to `Curl_llist_remove()`or `Curl_llist_destroy()` and
112the second is the `elem` pointer associated with removed node. The pointer
113that `Curl_node_elem()` would have returned for that node.
115## `Curl_llist_destroy`
117~~~c
118void Curl_llist_destroy(struct Curl_llist *list, void *user);
119~~~
121This removes all nodes from the `list`. This leaves the list in a cleared
122state.
124The function is infallible.
126## `Curl_llist_append`
128~~~c
129void Curl_llist_append(struct Curl_llist *list,
130 const void *elem, struct Curl_llist_node *node);
131~~~
133Adds `node` last in the `list` with a custom pointer to `elem`.
135The function is infallible.
137## `llist_insert_next`
139~~~c
140void llist_insert_next(struct Curl_llist *list,
141 struct Curl_llist_node *before,
142 const void *elem,
143 struct Curl_llist_node *node);
144~~~
146Adds `node` to the `list` with a custom pointer to `elem` immediately after
147the previous list `before`.
149The function is infallible.
151## `Curl_llist_head`
153~~~c
154struct Curl_llist_node *Curl_llist_head(struct Curl_llist *list);
155~~~
157Returns a pointer to the first node of the `list`, or a NULL if empty.
159## `Curl_node_uremove`
161~~~c
162void Curl_node_uremove(struct Curl_llist_node *node, void *user);
163~~~
165Removes the `node` the list it was previously added to. Passes the `user`
166pointer to the list's destructor function if one was setup.
168The function is infallible.
170## `Curl_node_remove`
172~~~c
173void Curl_node_remove(struct Curl_llist_node *node);
174~~~
176Removes the `node` the list it was previously added to. Passes a NULL pointer
177to the list's destructor function if one was setup.
179The function is infallible.
181## `Curl_node_elem`
183~~~c
184void *Curl_node_elem(struct Curl_llist_node *node);
185~~~
187Given a list node, this function returns the associated element.
189## `Curl_node_next`
191~~~c
192struct Curl_llist_node *Curl_node_next(struct Curl_llist_node *node);
193~~~
195Given a list node, this function returns the next node in the list.
Diagnostics4 git calls · 77 ms
CallStatusSizeTime077 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 · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=4
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 · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=25
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.0 KiB · hit48 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=48
git.response.bytes=2005
git.response.cache=HIT
git.response.duration_ms=48
git.fetch.wants=8daf58a36d4a8306b124edf0897276c91a945430
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=2005
git.pkt.payload.max=1984
git.sideband.band1.bytes=1983
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
a5e2c44f5ee9aedd
Request
4f5ae7b3…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format