Repository navigation
src/README.md: map the source folder, its threads and its locks #3875
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
0dc329c
61468d2
677a0d9
9b59d4f
691c1c5
24b8566
33202fa
8d81181
58b82bd
c2d091b
e93cca2
5e0ef26
32761c6
57b7cc4
5ce9925
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| <!-- | ||
| ### Copyright (c) 2026 | ||
|
|
||
| Author(s): | ||
| * mcfnord | ||
| * The Jamulus Development Team | ||
| --> | ||
|
|
||
| # Main Jamulus codebase | ||
|
|
||
| Licensed under the AGPL 3.0 or any later version; full text in [../COPYING](../COPYING). | ||
|
|
||
| ## Code overview | ||
|
|
||
| Jamulus is a client/server system. Each client encodes the audio from its sound device and sends it | ||
| to the server over UDP. The server decodes every client's stream and builds a separate mix for each | ||
| connected client, using that client's own fader gains, then re-encodes it and sends it back to be | ||
| decoded and played out. At both ends, arriving packets go through a jitter buffer first. | ||
|
|
||
| Background: [Performing Band Rehearsals on the Internet with Jamulus](https://jamulus.app/PerformingBandRehearsalsontheInternetWithJamulus.pdf), | ||
| Volker Fischer's case study, based on three years of weekly online rehearsals. | ||
|
|
||
| ## Directory contents | ||
|
|
||
| Code used by both client and server: | ||
|
mcfnord marked this conversation as resolved.
Resolved
|
||
|
|
||
| - [main.cpp](main.cpp) parses the command line and constructs a `CClient` or a `CServer`. The entrypoint of the application. | ||
| - [protocol.cpp](protocol.cpp) — Programmatic specification of the protocol. `CProtocol` contains message framing, acknowledgement and | ||
| retransmission. Wire format: [../docs/JAMULUS_PROTOCOL.md](../docs/JAMULUS_PROTOCOL.md). | ||
| - [channel.cpp](channel.cpp) — One connection to a peer, used by both client and server. `CChannel` holds the connection state and its | ||
| receive jitter buffer. | ||
| - [socket.cpp](socket.cpp) — The UDP socket shared by all sending and receiving. `CSocket`, `CHighPrioSocket` and the receive thread. | ||
| - [buffer.h](buffer.h) — The jitter buffer. `CNetBuf` and `CNetBufWithStats`, including the automatic size decision. | ||
| - [settings.cpp](settings.cpp) — Reads and writes the settings XML file. `CSettings`, specialised as `CClientSettings` and `CServerSettings`. | ||
| - [util.h](util.h) / [util.cpp](util.cpp) — Shared helpers. `CHighPrecisionTimer` (the server's frame clock) among others. | ||
| - [rpcserver.cpp](rpcserver.cpp) — The JSON-RPC transport. `CRpcServer` accepts TCP connections, checks the secret, and | ||
| dispatches each method to the handlers that the client or server half registers. | ||
| - [global.h](global.h) — Project-wide constants (frame size, default port, channel limit) and `CGenErr`. | ||
| - [signalhandler.cpp](signalhandler.cpp) — `CSignalHandler` turns SIGINT and SIGTERM into a clean shutdown. On the server, | ||
| SIGUSR1 also starts a new recording and SIGUSR2 toggles recording. | ||
| - [testbench.h](testbench.h) — `CTestbench` sends random protocol messages to a peer. Its only instance, in `main.cpp`, is | ||
| commented out. | ||
|
|
||
| Client only: | ||
|
|
||
| - [client.cpp](client.cpp) — The client's audio path. `CClient` and its single channel. | ||
| - [sound/](sound/) — The sound layer, one backend per platform. See [sound/README.md](sound/README.md). | ||
| - [plugins/audioreverb.cpp](plugins/audioreverb.cpp) — The reverb effect. `CAudioReverb`. | ||
| - [clientdlg.cpp](clientdlg.cpp), [clientsettingsdlg.cpp](clientsettingsdlg.cpp), | ||
| [audiomixerboard.cpp](audiomixerboard.cpp), [connectdlg.cpp](connectdlg.cpp), | ||
| [chatdlg.cpp](chatdlg.cpp) — The GUI. | ||
| - [levelmeter.cpp](levelmeter.cpp) — `CLevelMeter`, the LED-bar level meter. [multicolorled.cpp](multicolorled.cpp) — | ||
| `CMultiColorLED`, the status lights. | ||
| - [analyzerconsole.cpp](analyzerconsole.cpp) — `CAnalyzerConsole`, the dialog that graphs the error rate of each jitter | ||
| buffer size. | ||
| - [clientrpc.cpp](clientrpc.cpp) — The client half of the JSON-RPC API. | ||
|
|
||
| Server only: | ||
|
|
||
| - [server.cpp](server.cpp) — The server's frame cycle. `CServer` holds the channels and builds each client's mix. | ||
| - [serverlist.cpp](serverlist.cpp) — Directory registration and the server list. | ||
| - [recorder/](recorder/) — Recording of a session. `CJamController` and `CJamRecorder`. | ||
| - [serverlogging.cpp](serverlogging.cpp) — The connection log. | ||
| - [serverrpc.cpp](serverrpc.cpp) — The server half of the JSON-RPC API. | ||
| - [serverdlg.cpp](serverdlg.cpp) — The server GUI. | ||
| - [threadpool.h](threadpool.h) — `CThreadPool`, the worker pool behind `--multithreading`. | ||
|
|
||
| Platform code and resources: | ||
|
|
||
|
mcfnord marked this conversation as resolved.
Resolved
|
||
| - [android/](android/) — Android debug logging. | ||
| - [ios/](ios/) — The iOS application delegate. | ||
| - [mac/](mac/) — `CActivity`, which stops macOS throttling the process (App Nap, sleep), and the Dock badge. | ||
| - [res/](res/) — Images, icons, flags, instrument pictures and sounds. | ||
| - [translation/](translation/) — The `.ts` translation files, and the Windows installer's own strings in `wininstaller/`. | ||
|
|
||
| The JSON-RPC API ([rpcserver.cpp](rpcserver.cpp), [clientrpc.cpp](clientrpc.cpp), | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
| [serverrpc.cpp](serverrpc.cpp)) is documented in [../docs/JSON-RPC.md](../docs/JSON-RPC.md). | ||
|
|
||
| ## Threading | ||
|
|
||
| | thread | exists | started from | what runs on it | | ||
| |---|---|---|---| | ||
| | Qt main thread | always | — | the GUI; every protocol message body, parsed and created, on client and server; directory registration; JSON-RPC; and the server's complete frame cycle (see below) | | ||
| | `CSocketThread` | always | `CHighPrioSocket::Start()`, at `QThread::TimeCriticalPriority` | a blocking UDP receive loop. Audio packets are decoded into the jitter buffer synchronously, in `CChannel::PutAudioData` (client) or `CServer::PutAudioData` (server). Protocol messages are split across the two threads: `CProtocol::ParseMessageFrame` validates the frame here, then the body is re-emitted as a queued signal and `ParseMessageBody` runs it on the main thread. | | ||
| | audio driver threads | client | the sound driver | the backend callback, which runs `CClient::AudioCallback`: Opus decode of the received stream, Opus encode of the sound card input, and the UDP send of the encoded packet | | ||
| | `CHighPrecisionTimer` | server, except on Windows | `CHighPrecisionTimer::Start()`, at `QThread::TimeCriticalPriority` | only `emit timeout()` once per frame, plus the absolute-time sleep that paces it | | ||
| | `CThreadPool` workers | server with `--multithreading`, on more than one core | `CServer`'s constructor | Opus decode and mix/encode/send work, in per-block chunks handed out by `CServer::OnTimer` | | ||
| | recorder thread | server with recording | `CJamController` | `CJamRecorder`, fed by queued `AudioFrame` signals from the frame cycle | | ||
| | `QThreadPool` global pool | client GUI | the connect dialog | one task per listed server for the ping/info fan-out (`QtConcurrent::run`) | | ||
|
|
||
| **The server's frame cycle runs on the main thread.** The `CHighPrecisionTimer` thread only | ||
| emits `timeout()`. Its queued slot, `CServer::OnTimer`, does the jitter buffer drain, decode, | ||
| mix, encode and transmit — on the main thread. The TODO in | ||
| [util.cpp](util.cpp) notes the same escape from the timer thread. On Windows the pacer is a | ||
| plain `QTimer`, also main thread. With `--multithreading` the heavy blocks go to the pool, but | ||
| `OnTimer` waits for them. On a machine reporting one core, `CServer`'s constructor turns the | ||
| option back off, so no pool thread is created at all. | ||
|
|
||
| ### Locks | ||
|
|
||
| The locks taken from more than one thread: | ||
|
|
||
| | lock | protects | taken from | | ||
| |---|---|---| | ||
| | `CChannel::MutexSocketBuf` | the jitter buffer | put on `CSocketThread`; get from the client's driver callback or the server's frame cycle; re-init from the main thread | | ||
| | `CSocket::Mutex` | the send path of the shared UDP socket | every `SendPacket()` call: the driver callback (client), the frame cycle and pool workers (server), and protocol code on the main thread | | ||
| | `CServer::Mutex` | connect and disconnect of channels against the frame cycle | `CServer::OnTimer` holds it while it collects the connected channels and drains and decodes their jitter buffers, and releases it before mix and send; `CServer::PutAudioData` (`CSocketThread`) and the protocol slots (main thread) take it too | | ||
| | `CChannel::Mutex` | per-channel state: the enable flag, gain and pan tables, name | setters in protocol slots on the main thread; getters in the server's frame cycle | | ||
| | `CChannel::MutexConvBuf` | the send-side conversion buffer | `PrepAndSendPacket()` on the sending thread; re-init from the main thread | | ||
|
|
||
| **Smaller locks:** | ||
|
|
||
| - `CProtocol::Mutex` — queue of sent but not yet acknowledged messages | ||
| - `CServer::MutexChanOrder` — channel allocation in `FindChannel` and `FreeChannel` | ||
| - `CServer::MutexWelcomeMessage` — the welcome message string. Only `OnNewConnection` and | ||
| `SetWelcomeMessage` lock it. `OnCLReqServerFeatures`, `OnCLReqWelcomeMessage` and | ||
| `GetWelcomeMessage` read it without the lock, and all three run on the main thread. | ||
| - `CClient::MutexChannels` — client-side channel number map | ||
| - `CClient::MutexGainOrPan` — gain/pan message rate limiter | ||
| - `CClient::MutexDriverReinit` — serializes sound device re-initialization | ||
| - Sound layer locks (`MutexAudioProcessCallback`, `MutexDevProperties`, per-backend) — see [sound/README.md](sound/README.md) | ||
Uh oh!
There was an error while loading. Please reload this page.