commit d1a1631a05521279041a9ed41383d886e5580250 Author: Nick Mathewson nickm@torproject.org Date: Tue Nov 12 12:05:05 2019 -0500

01f-threads.md becomes threading.dox. --- .../01f-threads.md => src/lib/thread/threading.dox | 22 ++++++++++++---------- src/mainpage.dox | 3 +++ 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/HACKING/design/01f-threads.md b/src/lib/thread/threading.dox similarity index 56% rename from doc/HACKING/design/01f-threads.md rename to src/lib/thread/threading.dox index a0dfa2d40..e15d58440 100644 --- a/doc/HACKING/design/01f-threads.md +++ b/src/lib/thread/threading.dox @@ -1,26 +1,28 @@ +/**

-## Threads in Tor ## +@page threading Threading in Tor

Tor is based around a single main thread and one or more worker threads. We aim (with middling success) to use worker threads for CPU-intensive activities and the main thread for our networking. -Fortunately (?) we have enough cryptography that moving what we can of the -cryptographic processes to the workers should achieve good parallelism under most -loads. Unfortunately, we only have a small fraction of our -cryptography done in our worker threads right now. +Fortunately (?) we have enough cryptography that moving what we can +of the cryptographic processes to the workers should achieve good +parallelism under most loads. Unfortunately, we only have a small +fraction of our cryptography done in our worker threads right now.

Our threads-and-workers abstraction is defined in workqueue.c, which combines a work queue with a thread pool, and integrates the -signalling with libevent. Tor main instance of a work queue is +signalling with libevent. Tor's main instance of a work queue is instantiated in cpuworker.c. It will probably need some refactoring as more types of work are added.

-On a lower level, we provide locks with tor_mutex_t, conditions with -tor_cond_t, and thread-local storage with tor_threadlocal_t, all of -which are specified in compat_threads.h and implemented in an OS- -specific compat_*threads.h module. +On a lower level, we provide locks with tor_mutex_t in \refdir{lib/lock}, and +higher-level locking/threading tools in \refdir{lib/thread}, including +conditions (tor_cond_t), thread-local storage (tor_threadlocal_t), and more. +

Try to minimize sharing between threads: it is usually best to simply make the worker "own" all the data it needs while the work is in progress, and to give up ownership when it's complete.

+**/ diff --git a/src/mainpage.dox b/src/mainpage.dox index a5988aecf..a568d52fc 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -33,6 +33,9 @@ Tor repository. @subpage dataflow

@subpage certificates + +@subpage threading + **/

/**