One of my Favorite Comments
Many years ago, I built a market data server based on the Bloomberg API that was available on Solaris - back in the days when the Bloomberg Terminal was available on Solaris. In that code, I needed to solve a problem of thread starvation and in order not to confuse the Next Guy - which could have been me, I made sure to comment this code to get a reference to the "housekeeping mutex" in the object. This was all C++.
To this day, this is one of my favorite comments. It's just exactly what I want to write, tell people I think they can write:
/* * When any client or chat command wants to do something with the * server they need to get my housekeeping mutex and place a read * lock on it. The reason for this is that we are going to have * times when the controller knows that things aren't really stable * in the system and therefore we need to hold off on doing certain * things. Since this is a read-write lock, most of the time things * will run along swimmingly, but when there is maintenance underway * we will obtain a write lock and make the normal clients wait for * the maintenance to be done. */ CKFWRWMutex *BBGServerController::getHousekeepingMutex() { /* * With so many readers (clients) hitting the server at all hours, * we run into the problem that the write lock is almost impossible * to get. This is further hanpered by the fact that the pthread * read-write mutex doesn't specify the writers as having a higher * priority than the readers. So we can get a writer starvation. * * The solution is to have another mutex "in front" of the read-write * mutex that controls everything. The way this works is that all * clients need to call this method to get the housekeeping mutex. * The first thing they'll need to do here is to get a lock on the * "out of order" mutex and then release it right away. Most of the * time this will happen with little to no delay. However... when the * major housekeeping tasks arise, they lock this guy and *leave it * locked* so that the write lock that comes after it can wait for * the pending readers to get done and *then* obtain it's write lock. * * When the housekeeping maintenance is done, we unlock the write lock * and then unlock the "out of order" lock and this method can resume. * It's a clean process that allows me to prioritize the write lock * above the readers which is as it should be in this application. */ mOutOfOrderMutex.lock(); mOutOfOrderMutex.unlock(); return & mHousekeepingMutex; }
Writing comments like this just makes me smile.