diff options
author | Mikkel Krautz <mikkel@krautz.dk> | 2016-05-15 15:44:23 +0300 |
---|---|---|
committer | Mikkel Krautz <mikkel@krautz.dk> | 2016-06-24 01:03:11 +0300 |
commit | 5c0c8d8e58958c388af76aded527b8a9e6d2ce11 (patch) | |
tree | 0d8c9187e565dc35291b524c24ec9be46aeb6e67 /src/murmur/Server.h | |
parent | b33e1ac7f24b01726831a8b68a9095f45611105c (diff) |
Add documentation for qrwlVoiceThread.
Diffstat (limited to 'src/murmur/Server.h')
-rw-r--r-- | src/murmur/Server.h | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/src/murmur/Server.h b/src/murmur/Server.h index bba2dcc64..400968c8b 100644 --- a/src/murmur/Server.h +++ b/src/murmur/Server.h @@ -212,6 +212,51 @@ class Server : public QThread { quint32 uiVersionBlob; QList<QSocketNotifier *> qlUdpNotifier; + /// This lock provides synchronization between the + /// main thread (where control channel messages and + /// RPC happens), and the Server's voice thread. + /// + /// These are the only two threads in Murmur that + /// access a Server's data. + /// + /// The easiest way to understand the locking strategy + /// and synchronization between the main thread and the + /// Server's voice thread is by using the concept of + /// ownership. + /// + /// A thread owning an object means that it is the only + /// thread that is allowed to write to that object. To + /// make changes to it. + /// + /// Most data in the Server class is owned by the main + /// thread. That means that the main thread is the only + /// thread that writes/updates those structures. + /// + /// When processing incoming voice data (and re- + /// broadcasting) that voice data), the Server's voice + /// thread needs to access various parts of Server's data, + /// such as qhUsers, qhChannels, User->cChannel, etc. + /// However, these are owned by the main thread. + /// + /// To ensure correct synchronization between the two + /// threads, the contract for using qrwlVoiceThread is + /// as follows: + /// + /// - When the Server's voice thread needs to read data + /// owned by the main thread, it must hold a read lock + /// on qrwlVoiceThread. + /// + /// - The Server's voice thread does not write to any data + /// that is owned by the main thread. + /// + /// - When the main thread needs to write to data owned by + /// itself that is accessed by the voice thread, it must + /// hold a write lock on qrwlVoiceThread. + /// + /// - When the main thread needs to read data that is owned + /// by itself, it DOES NOT hold a lock on qrwlVoiceThread. + /// That is because ownership of data guarantees that no + /// other thread can write to that data. QReadWriteLock qrwlVoiceThread; QHash<unsigned int, ServerUser *> qhUsers; QHash<QPair<HostAddress, quint16>, ServerUser *> qhPeerUsers; |