src/README.md: map the source folder, its threads and its locks

[mcfnord]

MY LLM WROTE:

Short description of changes

src/ has no README. This adds one: a map for a reader new to the code — which class lives where, which threads exist at runtime, and which lock protects what. Same shape as the section recently proposed for src/sound/README.md in #3873: it describes how the code behaves today, asserts no intent, and ends with an explicit list of what is still missing.

What it covers:

• Where things live — one line per major class, split into shared / client-only / server-only, with links to the protocol and JSON-RPC docs.
• Threads — a table of every thread: the Qt main thread, CSocketThread, the audio driver threads, CHighPrecisionTimer's thread, the CThreadPool workers, the recorder thread, and the connect dialog's use of the global pool. Followed by the three facts easiest to miss: the server's complete frame cycle (CServer::OnTimer) executes on the main thread — the TimeCriticalPriority timer thread only paces a queued emit timeout() (confirmed with a debugger on Linux, and the TODO in util.cpp says the same); CSoundBase inherits QThread but that thread is never started; the client sends audio from inside the driver callback while receiving on CSocketThread.
• Locks — a table of the five locks taken from more than one thread (MutexSocketBuf, CSocket::Mutex, CServer::Mutex including exactly which part of OnTimer holds it, CChannel::Mutex, MutexConvBuf), each with what it protects and the threads that take it, plus one line each for the smaller ones.
• Not yet documented — the jitter buffer size algorithm, connection lifecycle, directory registration, the recorder, logging, signal handling, the GUI classes.

The thread table is measured, not read: each identity was confirmed by breaking on the function in a release build under gdb on Linux and recording which thread hit (CServer::OnTimer and CProtocol::ParseMessageBody on the main thread, CServer::PutAudioData and CChannel::PutAudioData on CSocketThread, CClient::ProcessAudioDataIntern on the JACK callback thread, CHighPrecisionTimer::run on its own thread).

Two design choices, offered for discussion since later doc files could follow the pattern:

• Every cross-reference is a relative link whose link text is the path itself — [channel.cpp](channel.cpp), [../docs/JAMULUS_PROTOCOL.md](../docs/JAMULUS_PROTOCOL.md). Rendered on GitHub, the map becomes browseable: every named file is one click away. Read raw in a terminal or an editor, each link degrades to the path plus punctuation, so the text still works for a reader without a browser.
• No link carries a line number, because line numbers go stale with the next commit to the file. Functions, classes and members are named in backticks instead, so a plain grep finds them from either the rendered or the raw form.

CHANGELOG: SKIP

Context: Fixes an issue?

No issue. Follows #3873, which starts the sound-layer half of the same documentation; this file links to it rather than repeating it.

Does this change need documentation? What needs to be documented and how?

This is the documentation. Developer-facing, so it belongs next to the code rather than on the website.

Status of this Pull Request

Working implementation. Every statement is checkable against the tree at the commit it was written on, and the thread identities were verified at runtime rather than inferred from the source.

What is missing until this pull request can be merged?

Review. One open question for reviewers: whether the license header on a brand-new documentation file should carry the full historical GPL paragraph or only the AGPL block used here.

Checklist

• I've verified that this Pull Request follows the general code principles
• I tested my code and it does what I want
• My code follows the style guide
• I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
• I've filled all the content above

No checks run on this one: autobuild.yml carries paths-ignore: '**README.md' and coding-style-check.yml only triggers on **.cpp/**.h, so the fourth box stays unticked rather than claiming a green run that never happened.

[ann0see]

I'd aim this at human contributors for now.

[ann0see]

Review. One open question for reviewers: whether the license header on a brand-new documentation file should carry the full historical GPL paragraph or only the AGPL block used here.

AGPL. But I think it's weird as is. I'd think that a HTML comment for the full license would be enough and a visible short link to the license file. But @pljones should judge. I really dislike a wall of text first just stating the license. Nobody reads it.

[mcfnord]

I'd aim this at human contributors for now.

I believe if we write for a human audience, we will dramatically improve LLM outcomes "for free".

[pljones]

Maybe a separate Channel.md as it's pretty much "here's what Jamulus really is".

[ann0see]

No. I think we should have specifics in the code directly.

[mcfnord]

I think we should have specifics in the code directly.

You said this somewhere else... these are Markdown files in the repo, which means "in the code" to me, but are you saying you'd prefer detailed comments inline within C++ source code files?

[ann0see]

Have a somewhat larger comment in the cpp or h file describing roughly what this file does/fits into the architecture. The markdown files have a very high level description or none at all.

E.g. the protocol has in source file docs:

jamulus/src/protocol.cpp

Lines 47 to 72 in 4a43f6f

	/*
	Protocol message definition
	---------------------------
	- All messages received need to be acknowledged by an acknowledge packet (except
	of connection less messages)
	MAIN FRAME
	----------
	+-------------+------------+------------+------------------+ ...
	| 2 bytes TAG | 2 bytes ID | 1 byte cnt | 2 bytes length n | ...
	+-------------+------------+------------+------------------+ ...
	... --------------+-------------+
	... n bytes data | 2 bytes CRC |
	... --------------+-------------+
	- TAG is an all zero bit word to identify protocol messages
	- message ID defined by the defines PROTMESSID_x
	- cnt: counter which is increment for each message and wraps around at 255
	- length n in bytes of the data
	- actual data, dependent on message type
	- 16 bits CRC, calculated over the entire message and is transmitted inverted
	Generator polynom: G_16(x) = x^16 + x^12 + x^5 + 1, initial state: all ones

[mcfnord]

🤖 AI: Pushed. Two of these are corrections to the Threads table, found by binding each quantified sentence to a command that would make it false rather than one that confirms it.

The CSocketThread row said protocol frames are not parsed there. CProtocol::ParseMessageFrame is called on exactly that thread — its only call site — and does the tag, length and CRC check plus extraction of the body, ID and counter. What crosses to the main thread is the body, via the queued signal, where ParseMessageBody runs it. The protocol API splits frame from body by name and the row asserted the inverse; the main-thread row inherited the same error and now reads "message body".

The CThreadPool row said "server with --multithreading". CServer's constructor also requires more than one core: at idealThreadCount() == 1 it logs found only one core, disabling multithreading, clears the flag and creates no pool. A single-core server is a normal deployment, so that row described threads which do not exist there.

The rest is review follow-up: the licence transition note is dropped from this new file, Client only and Server only are bulleted like the shared list, and the blank lines an earlier suggestion-apply left in the header block are collapsed.

[ann0see]

@pljones do we really need to put the full license text - even as comment - into the file? It's better now though (since we have this short disclaimer). For code the header is fine, but for markdown files it just seems odd.

[ann0see]

I'll need to verify the accuracy, but from the philosophy and style, I think it's good now. Basically serves as index which is good.