mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-09-23 14:34:58 +02:00
469051f650
I started this repository a while ago to work on documentation for Tor's internals. It needs substantial revision, but first, let's get it copied into Tor's repository. These files are copied, "warts and all", from the tor-guts.git repo, commit de1e34259178b09861c0dea319c760fa80d0099a. Part of 31819.
44 lines
1.6 KiB
Markdown
44 lines
1.6 KiB
Markdown
|
|
## Collections in tor
|
|
|
|
### Smartlists: Neither lists, nor especially smart.
|
|
|
|
For historical reasons, we call our dynamic-allocated array type
|
|
"smartlist_t". It can grow or shrink as elements are added and removed.
|
|
|
|
All smartlists hold an array of void \*. Whenever you expose a smartlist
|
|
in an API you *must* document which types its pointers actually hold.
|
|
|
|
<!-- It would be neat to fix that, wouldn't it? -NM -->
|
|
|
|
Smartlists are created empty with smartlist_new() and freed with
|
|
smartlist_free(). See the containers.h module documentation for more
|
|
information; there are many convenience functions for commonly needed
|
|
operations.
|
|
|
|
|
|
### Digest maps, string maps, and more.
|
|
|
|
Tor makes frequent use of maps from 160-bit digests, 256-bit digests,
|
|
or nul-terminated strings to void \*. These types are digestmap_t,
|
|
digest256map_t, and strmap_t respectively. See the containers.h
|
|
module documentation for more information.
|
|
|
|
|
|
### Intrusive lists and hashtables
|
|
|
|
For performance-sensitive cases, we sometimes want to use "intrusive"
|
|
collections: ones where the bookkeeping pointers are stuck inside the
|
|
structures that belong to the collection. If you've used the
|
|
BSD-style sys/queue.h macros, you'll be familiar with these.
|
|
|
|
Unfortunately, the sys/queue.h macros vary significantly between the
|
|
platforms that have them, so we provide our own variants in
|
|
src/ext/tor_queue.h .
|
|
|
|
We also provide an intrusive hashtable implementation in src/ext/ht.h
|
|
. When you're using it, you'll need to define your own hash
|
|
functions. If attacker-induced collisions are a worry here, use the
|
|
cryptographic siphash24g function to extract hashes.
|
|
|