One of my Favorite Comments

Code Monkeys

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.