“Foshizzle” is a modified version of the Clang compiler which supports Eubonicode++ (an alternate C++ syntax). Foshizzle supports all the existing features of Clang, but with extensions to more fully express your gansta style. All the regular C++ syntax still works, but you can now substitute Eubonicode++ keywords and operators (see below).

Here’s a sample method that calculates factorials (Note: the semicolons can be replaced with a certain expletive):

int factorialz(int n)
{
    int rezult be 1;
    slongas (n bepimpin 0)
    {
        rezult be rezult dimes n;
        dissin n;
    }
    putou rezult;
}

I can’t take all the credit. I was inspired by the Iowa State students that first created Eubonicode (webpage no longer available).

Here are my Clang modifications: ebpp-clang30rc4.patch

Build instructions are near the end of this post.

How It Happened

I periodically venture off into the h4x0r wilderness and pour myself into some random project. It always starts out innocently enough, but the project soon takes on a life of it’s own. This time was no different… except it happened over Thanksgiving (much to my wife’s chagrin).

Being the charismatic socialite that I am (sarcasm), I was digging through the C++11 spec on Thanksgiving. What struck me was how much of my language design course I had forgotten, and it really bugged me. It’s one of those required courses in the CompSci graduate program that I loathed having to take, but turned out to be invaluable (don’t get me started on the database and UI design courses… blah).

Long story less long, I started refreshing on compilers (read this for inspiration). I’d heard about Clang and LLVM awhile ago, and I remembered their focus on modularity, maintainability, and all sorts of other *ability’s. I figured it’d be a good place to start, so I download the source code and dug through it (watch this video for background on Clang).

Stepping through Clang in a debugger sounded like a great way to start, but I quickly had mental stack overflow through the recursive parsing code. Okay, time for plan B. Common wisdom says that a good way to learn a piece of code is to try and fix a bug. So I went to the Clang bug list looking for a starter task, but all the “interesting” tasks were way too large in scope for a Clang newb like me.

Time to invent plan C: make a small tweak to the language and see if I can get it working. I remembered a few years ago that some students from Iowa State built an Eubonicode compiler for a language class they had. It got quite a few laughs around the office and was always wishing for a working compiler. So I decided take their idea and replace ‘while’ with ‘slongas’… and an hour later I had it working (which is testament to the readability of the Clang code… it’s very well commented).

Not satisfied to stop there, I moved on to other keywords… simple, once you get comfortable with how the code’s laid out. “What about operators and punctuators?”, I wondered. After a few failed attempts, it dawned on me that C++ has aliases for operators (‘and_eq’ can be used in place of ‘&=’, etc). Instead of heavily modifying the parser/lexer, I started looking for how Clang handled these aliases… maybe I could just add some more. Turns out, it fairly simple to add new aliases, so ‘==’ got overloaded with ‘sameas’, ‘!=’ got overloaded with ‘aint’, etc… and it worked! Sweet!

After all that, I dug a little into the preprocessor and figured out how to support ‘#mahomie’ in place of ‘#include’. Simple enough. I dug a little into the build stuff and changed the name from ‘clang’ to ‘foshizzle’… cool. I little bit of frustration later, and I had it recognizing ‘*.opp’ and ‘*.ho’ as source and header files, respectively.

Three days after I started, I had a fully functional Eubonicode++ compiler and a lot deeper understanding of how a production C++ compiler works. I can’t stress enough that this project would never have happened if the Clang code wasn’t written so well. Kudos to the Clang team.

I really enjoyed this project, and I hope you get half the fun out of it I did. Next time you have a coding task, consider adding a litta gansta sizzle

C++ To Eubonicode++ Mapping

•  *.cpp -> *.opp
• *.h -> *.ho

Many thanks to Sean Tegtmeyer for helping with the syntax definition.

Building Foshizzle

I highly suggest building Clang without my changes first and verify that you have it working correctly. Then it should be simple to apply my patch and rebuild. I did all my work on Fedora 16, so your mileage may vary on other distros or OSes.

Note: If you have any problems building LLVM or Clang, please refer to their build page: Getting Started

1. Create a new directory (e.g. “foshizzle”).
2. Within the “foshizzle” directory, create the following directories: “build”, “src”, “install”
3. Checkout the LLVM source code into the “src” directory:
• svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE_30/rc4 ./src
4. Create a new directory for the Clang source within the LLVM “tools” directory:
• mkdir src/tools/clang
5. Checkout the Clang source code into the “src/tools/clang” directoy:
• svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE_30/rc4 ./src/tools/clang
6. Change directories into the “build” directory.
7. Configure the Clang/LLVM build and point it to the “install” directory you created earlier:
• ../src/configure --prefix=<path>/<to>/<foshizzle>/install
8. Build (takes quite a while): make
9. Install: make install
10. Compile some test code to make sure it works: install/bin/clang++ yourtestcode.cpp

Only continue on once the unmodified version of Clang is working.

1. Download my patch file: ebpp-clang30rc4.patch
2. Change directories to where the Clang source is (src/tools/clang).
3. Apply the patch: patch -p0 -i ebpp-clang30rc4.patch
4. Change back to the “build” directory.
5. Build: make
6. Install: make install
7. Test: install/bin/foshizzle++ yordopecodez.opp

You can also build the sample code below.

Sample Code

baseclaz.ho, friendclaz.ho, main.opp

Building

install/bin/foshizzle++ main.opp

Program Output

baseclaz: protected = 1, private = 1
derivedclaz: protected = 0, private = 1
friendclaz: friend private = 0

Factorial(7) = 5040

static const uint32_t kCrc32Table[256] = {
    0x00000000, 0x77073096, 0xee0e612c, 0x990951ba,
    0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3,
    0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988,
    0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91,
    0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
    0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7,
    0x136c9856, 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec,
    0x14015c4f, 0x63066cd9, 0xfa0f3d63, 0x8d080df5,
    0x3b6e20c8, 0x4c69105e, 0xd56041e4, 0xa2677172,
    0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
    0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940,
    0x32d86ce3, 0x45df5c75, 0xdcd60dcf, 0xabd13d59,
    0x26d930ac, 0x51de003a, 0xc8d75180, 0xbfd06116,
    0x21b4f4b5, 0x56b3c423, 0xcfba9599, 0xb8bda50f,
    0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
    0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d,
    0x76dc4190, 0x01db7106, 0x98d220bc, 0xefd5102a,
    0x71b18589, 0x06b6b51f, 0x9fbfe4a5, 0xe8b8d433,
    0x7807c9a2, 0x0f00f934, 0x9609a88e, 0xe10e9818,
    0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
    0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e,
    0x6c0695ed, 0x1b01a57b, 0x8208f4c1, 0xf50fc457,
    0x65b0d9c6, 0x12b7e950, 0x8bbeb8ea, 0xfcb9887c,
    0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 0xfbd44c65,
    0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
    0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb,
    0x4369e96a, 0x346ed9fc, 0xad678846, 0xda60b8d0,
    0x44042d73, 0x33031de5, 0xaa0a4c5f, 0xdd0d7cc9,
    0x5005713c, 0x270241aa, 0xbe0b1010, 0xc90c2086,
    0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
    0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4,
    0x59b33d17, 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad,
    0xedb88320, 0x9abfb3b6, 0x03b6e20c, 0x74b1d29a,
    0xead54739, 0x9dd277af, 0x04db2615, 0x73dc1683,
    0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
    0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1,
    0xf00f9344, 0x8708a3d2, 0x1e01f268, 0x6906c2fe,
    0xf762575d, 0x806567cb, 0x196c3671, 0x6e6b06e7,
    0xfed41b76, 0x89d32be0, 0x10da7a5a, 0x67dd4acc,
    0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
    0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252,
    0xd1bb67f1, 0xa6bc5767, 0x3fb506dd, 0x48b2364b,
    0xd80d2bda, 0xaf0a1b4c, 0x36034af6, 0x41047a60,
    0xdf60efc3, 0xa867df55, 0x316e8eef, 0x4669be79,
    0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
    0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f,
    0xc5ba3bbe, 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04,
    0xc2d7ffa7, 0xb5d0cf31, 0x2cd99e8b, 0x5bdeae1d,
    0x9b64c2b0, 0xec63f226, 0x756aa39c, 0x026d930a,
    0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
    0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38,
    0x92d28e9b, 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21,
    0x86d3d2d4, 0xf1d4e242, 0x68ddb3f8, 0x1fda836e,
    0x81be16cd, 0xf6b9265b, 0x6fb077e1, 0x18b74777,
    0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
    0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45,
    0xa00ae278, 0xd70dd2ee, 0x4e048354, 0x3903b3c2,
    0xa7672661, 0xd06016f7, 0x4969474d, 0x3e6e77db,
    0xaed16a4a, 0xd9d65adc, 0x40df0b66, 0x37d83bf0,
    0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
    0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6,
    0xbad03605, 0xcdd70693, 0x54de5729, 0x23d967bf,
    0xb3667a2e, 0xc4614ab8, 0x5d681b02, 0x2a6f2b94,
    0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d,
}; // kCrc32Table

class Crc32
{
public:
    Crc32() { Reset(); }
    ~Crc32() throw() {}
    void Reset() { _crc = (uint32_t)~0; }
    void AddData(const uint8_t* pData, const uint32_t length)
    {
        uint8_t* pCur = (uint8_t*)pData;
        uint32_t remaining = length;
        for (; remaining--; ++pCur)
            _crc = ( _crc >> 8 ) ^ kCrc32Table[(_crc ^ *pCur) & 0xff];
    }
    const uint32_t GetCrc32() { return ~_crc; }

private:
    uint32_t _crc;
};

Note: I always have uint32_t defined in Windows, so you may have to define it yourself or use the Microsoft intrinsic unsigned __int32.

>4. Is it possible to include a Visual Studio solution in the
>distrubution to make it more convenient for Windows developers to
>use live555?
>5. Is it possible for live555 to generate adequate makefiles for
>Windows systems with development environments newer than Visual
>Studio 2003?

I have no current plans to change this. (These days, fewer and fewer people seem to be using Windows for development of system software.)

Regardless, Live555 works fine on Windows and is actually quite easy to build. Simply do the following:

1. Open the ‘win32config’ file and change the TOOLS32=... variable to your VS2008 install directory. For me, it’s TOOLS32=C:\Program Files\Microsoft Visual Studio 9.0\VC
2. In ‘win32config’, modify the LINK_OPTS_0=... line from msvcirt.lib to msvcrt.lib. This fixes the link error:
   LINK : fatal error LNK1181: cannot open input file 'msvcirt.lib'
3. Open the Visual Studio command prompt.
4. From the ‘live’ source directory, run genWindowsMakefiles
5. Now you’re ready to build. Simply run the following commands:

   cd liveMedia
   nmake /B -f liveMedia.mak
   cd ..\groupsock
   nmake /B -f groupsock.mak
   cd ..\UsageEnvironment
   nmake /B -f UsageEnvironment.mak
   cd ..\BasicUsageEnvironment
   nmake /B -f BasicUsageEnvironment.mak
   cd ..\testProgs
   nmake /B -f testProgs.mak
   cd ..\mediaServer
   nmake /B -f mediaServer.mak

That’s it. You should be good to go.

1. It’s installed by default on most distros (as opposed to the sysstat tools).
2. It gives the idle time in percentage normalized to 100% (as opposed to /proc/stat which requires knowledge of the jiffy’s interval, which can vary).

function cpu_load(interval)
   interval = interval or 1
   local f = io.popen('top -bp$$ -d ' .. interval .. ' -n 2')
   local s = f:read('*all')

   -- Find the idle times in the stdout output
   local tokens = s:gmatch(',%s*([%d%.]+)%%%s*id')

   -- We're interested in the 2nd 'top' idle time
   local ii = 1
   for idle in tokens do
      if ii == 2 then
         return 100.0 - tonumber(idle)
      end
      ii = ii + 1
   end
end

You can call it from the Lua shell as:

> load = cpu_load()
> print(load)
43.7

#ifdef WIN32
    #ifndef NAN
        static const unsigned long __nan[2] = {0xffffffff, 0x7fffffff};
        #define NAN (*(const float *) __nan)
    #endif
#endif

This code is adapted from an MSDN example.

Note: This post assumes you are already familiar with the socket extensions for IPv6 (RFC 3493).

Linux and Mac
Good news… they both fully support RFC 3493.

Windows
Windows IPv6 support varies based on which version you’re targeting. Microsoft started adding IPv6 in Windows 2000, and they’ve continued adding more of the socket extensions as time went on. Most of the core functionality is present in XP, and what’s missing is easily replaced by using Winsock calls directly (more on this later).

Windows gained IPv6 support while RFC 2553 was still the supported standard. Since then, it has been deprecated by RFC 3493. However, Microsoft doesn’t want to break existing code written against it’s API, so the older API lives on. The main impact of this is that sockaddr_in6 and sockaddr_storage are slightly different on Windows than Mac and Linux. The size of the structures across platforms is the same (the sa_family_t member was shortened), it’s just that the Windows structures don’t begin with the length member. For example:

// Linux and Mac
struct sockaddr_in6 {
    uint8_t      sin6_len;    /* Added in RFC 3493 */
    sa_family_t  sin6_family;
    ...
};
struct sockaddr_storage {
    uint8_t      ss_len;      /* Added in RFC 3493 */
    sa_family_t  ss_family;
    ...
};

// Windows
struct sockaddr_in6 {
    sa_family_t  sin6_family;
    ...
};
struct sockaddr_storage {
    sa_family_t  ss_family;
    ...
};

I’ve never had a problem with this, because the size of sockaddr_in6 is easily determined (sizeof(sockaddr_in6)) and I always end up casting sockaddr_storage to the specific type (sockaddr_in or sockaddr_in6) based on ss_family.

Besides the data structure differences, it’s important to remember that Microsoft added IPv6 support over multiple versions. Support first appeared in Windows 2000, but more of the extensions have been added over time. Most of the core functionality was present in XP (including multicast), but not everything is implemented as of Windows 7. It’s annoying, but I will say that what’s missing is easily replaced by using Winsock calls directly.

Here’s the breakdown of IPv6 socket extensions by Windows version:

As you can see, you may still have to call Winsock directly depending on what version of Windows you are targeting. In my opinion, programming IPv6 on Windows is a lot easier if you only support XP and later, but I know that’s not always possible.

Summary

Modern operating systems all support IPv6. However, for business reasons, Windows has a slightly older version of the socket API which requires special consideration. My goal was to enumerate those differences to help make the transition to IPv6 smoother. Writing cross-platform code can be a fun challenge at times, but it’s also a little tedious. Hopefully, this post helps ease the pain.

// Returns the address family of an address or hostname.
// AF_INET, AF_INET6, or -1 on error.
int getaddrfamily(const char *addr)
{
    struct addrinfo hint, *info =0;
    memset(&hint, 0, sizeof(hint));
    hint.ai_family = AF_UNSPEC;
    // Uncomment this to disable DNS lookup
    //hint.ai_flags = AI_NUMERICHOST;
    int ret = getaddrinfo(addr, 0, &hint, &info);
    if (ret)
        return -1;
    int result = info->ai_family;
    freeaddrinfo(info);
    return result;
}

See RFC 3493 for more information on the latest socket API for dealing with IPv6.

Note: This is intended to be a pragmatic guide for engineers evaluating codecs. It is not a comprehensive treatment of the subject. The goal is to give readers a solid overview and some practical ideas.

Get Familiar with Psychoacoustics

Psychoacoustics is the study of how humans perceive sound. As you might expect, we humans don’t process sound in a perfect, linear fashion. The physical shape of the ear, the transfer function of the Basilar membrane, and the psychological interpretation of the data all affect how we perceive sound (and by extension, how “good” an audio codec sounds to us).

I highly recommend you start by reading this excerpt from Surround Sound: Psychoacoustics Part 1, by Tomlinson Holman (he created THX for Lucasfilm).

Understand the Codec

Make sure you understand the codec you are testing; not necessarily the implementation, but what tools (i.e. methods) the codec uses for compression. Many codecs have different “profiles”, which describe what subset of available tools are used (e.g. AAC). You should also have some idea how each compression tool works and any short-comings it has. This will help guide you in selecting reference audio samples and knowing what artifacts to listen for.

For an introduction to modern audio compression, read Audio Coding: An Introduction to Data Compression Part 1, and Part 2 (discusses MP3 and AAC). I actually suggest buying the book “Introduction to Data Compression”, by Khalid Sayood.

Understand the API

Make sure you actually read the codec documentation and look at any available code samples. This step has more to do with due-diligence than anything, as I haven’t seen a codec API we couldn’t work with, but you need to do this. This will also help you scope the work required to get a working encoder/decoder for future steps (if your lucky, the sample code can be used).

Choose the Reference Audio Samples

An effective test requires multiple audio samples with different characteristics. There are many types of artifacts a codec can introduce, and your choice of audio samples will dictate how easy they are to detect. It’s also important to pick samples that reflect the actual types of sound the codec to have to deal with. For example, if the final system will primarily be encoding speech, then you should choose more speech-oriented references as opposed to music samples.

Some characteristics you might consider:

• Transients (snare drum): Sensitive to pre-echo and noise “smearing”.
• Tonal structure (clarinet, saxophone): Sensitive to noise and “roughness”.
• Natural speech (male and female voices of various languages): Sensitive to distortion and smearing of “attacks”.
• Complex sound (bag pipes): Stresses the codec.
• High bandwidth (bag pipes): Loss of high frequencies and program-modulated high frequency noise.

It is also possible to use synthetic sounds and sweeps, but this is only recommended for the automated objective tests below.

As a basic guideline, you need 10-25 second “raw” samples recorded at the highest sample rate your system needs to work with. It is vital that the samples you choose have never been compressed with a lossy codec (mp3, AAC, etc)… that would severally limit the quality of your test. For sample rate and size, I suggest 48kHz 16-bit PCM, but a lower rate/size makes sense if the final system is limited in this area. It also makes sense to use a sample rate of 44.1kHz, since many quality audio samples can be ripped losslessly from CD. Just keep in mind that the objective PEAQ test mentioned below requires 48kHz 16-bit PCM, so up-sampling may be required.

The audio samples can be stored in whatever container format you want (raw, WAV, etc) as long as your codec test application can unpack it. This is important to keep in mind… you don’t want to accidentally run the WAV header through the codec (yes, I’ve done this). The container format is more of a practical issue, but it was worth mentioning.

Generate Various Test Samples and Observe CPU Load

This step is pretty straight-forward: wrap the codec in an application and encode the reference audio samples at different bit rates. You should choose bit rates that represent the full spectrum of bit rates that will be used in the final system. While you’re encoding, track the CPU usage on the codec and how many cores it’s using. You may even want to do a separate test running many encodes in parallel (this works nicely if the CPU usage is too low to measure accurately). Make sure to consider application overhead and disk I/O when making measurements.

After encoding, you need to decode back to raw PCM. Clearly label your files so you know what bit rate each one was encoded with. These decoded test samples are what we will be comparing to the original reference samples.

Do a Subjective Test

How you conduct your subjective testing will depend on several factors, such as time constraints, cost, and the required test precision. At the low end, you could simply listen to the test samples in a pair of headphones and judge the quality yourself. For a high precision test, you could do a full ITU BS.1116 test using “expert listeners” in a controlled environment. While these examples represent the extremes, there are many permutations that can give you the desired quality of results.

The most common subjective test is called a “double-blind triple-stimulus with hidden reference” test. The listener hears three samples (commonly labeled A, B, and C) for a period of 10 to 25 seconds. A is always the original reference sample. The next two samples, B and C, are randomly assigned either the test sample from the codec or the original reference sample played again (called the “hidden reference”). The listener must then rate the difference between B and A, and C and A, not knowing which one is the test sample. The grading scale is:

• 5.0 Imperceptible
• 4.0 Perceptible, but not annoying
• 3.0 Slightly annoying
• 2.0 Annoying
• 1.0 Very annoying

Ideally, you would conduct several tests and average the results together. If you do the listening test yourself, your results will be limited to your listening skills and understanding of audio codec artifacts. Here’s a summary of factors that affect the quality of your results:

• The quality of the listener.
• The choice of audio samples.
• The number and duration of the testing.
• The testing environment, including speaker/headphone quality, room design, and listener placement.
• The quality of randomization of sample order to remove any correlation between samples.
• Proper statistical analysis of the combined test results.

A proper subjective test is both expensive and time consuming. It’s important to find the right balance for your particular needs.

Do an Objective Test

Evaluating a codec objectively requires testing methods that correlate well to actual human perception. You can’t simply measure the distortion introduced by the codec using traditional measurements like Signal-to-Noise ratio (S/N) and Total-Harmonic-Distortion (THD), because they don’t correlate well to perceived audio quality. Some distortion is imperceptible to the human ear, and codecs take advantage of this to increase the compression ratio.

Fortunately, the ITU has standardized an objective audio test called PEAQ (BS.1387). The acronym stands for Perceptual Evaluation of Audio Quality. PEAQ uses software to model the entire human auditory system (including blood flow noise in the inner ear) to generate a set of metrics that are used to give a final “quality” score. The original reference signal is compared to a signal run through the codec, and the result is a real number between 0.0 and -4.0. The result is interpreted on the following scale:

• 0.0 = Imperceptible
• -1.0 = Perceptible but not annoying
• -2.0 = Slightly annoying
• -3 .0= Annoying
• -4.0 = Very annoying

Obviously, values closer to zero are better.

The test was developed by a similar group of audio experts that developed BS.1116 (mentioned above) and the results have been validated against a long list of subjective tests done using expert listeners.

There are several free and commercial software packages available for doing PEAQ tests. The best free package I’ve found is AFsp from the McGill Telecommunications and Signal Processing Lab. There’s also peaqb, but there’s a comment that it gives incorrect results. AFsp worked great in my tests and included some helpful tools like CompAudio and InfoAudio.

Summary

Hopefully this post has given you a good starting point and some practical ideas for testing audio codecs. My goal was to provide a pragmatic approach with different options depending on what your actual evaluation needs are. This is in no way a comprehensive treatment of the subject; only an overview. I highly suggest reading some of the books I referenced if you’d like a deeper treatment of the subject. Either way, I hope you found this post helpful.

ct>

Here’s a copy of the video if it is ever removed (13MB, 3gp).

Lua Reference Card (PDF)

typedef enum _TYPE {
    TYPE_FOO = 0,
    TYPE_BAR,
    TYPE_BAZ,
    TYPE_MAX
} TYPE;

bool create(const TYPE type);

To me, it makes the most sense to call create() from Lua with syntax like:

> create(type.foo)

Ideally, we’d also like the following:

1. The enumeration is const, and can’t be altered from Lua code.
2. The C++ implementation of create() could validate the type passed to it is the expected type.

Unfortunately, this isn’t as straight-forward as everything else I’ve done with Lua.

Solution (i.e. cut-to-the-chase and explain later)

Okay, I’m a practical guy… download lua_typed_enums.h and include it in your code. Then you can add the enums shown above to Lua by calling add_enum_to_lua():

add_enum_to_lua( L, "type",
    "foo", TYPE_FOO,
    "bar", TYPE_BAR,
    "baz", TYPE_BAZ,
    0 );

Your enums are now available in Lua as:

type.foo
type.bar
type.baz

Now, your C++ code that takes TYPE as an input and returns a boolean would be written as follows:

static int lua_create( lua_State *L )
{
    if( !check_enum_type( L, "type", -1 ) ) {
        /* error */
    }

    int value = get_enum_value( L, -1 );

    /* do something cool */

    lua_pushboolean( L, 1 );
    return (1);
}

You can now call your create() method from Lua how we wanted:

> create(type.bar)

Look at the comments in the header file if you want more info about using add_enum_to_lua(), check_enum_type(), and get_enum_value().

How it Works

There’s no direct way to map the expected behavior of C-enums into Lua (const-ness with typing). What I did was to create a read-only Lua table representing the enumerated type and then make each value in that table have a defined type.

Let’s deal with the first task: making a read-only table. This is pretty well documented on the web, but I’ve included a drawing below that would have helped me a lot in the beginning. Let’s assume we want to represent our enum as a Lua table. We could visualize it as follows:

We could still use the type.foo syntax with this table, but a user could assign a new value to the enum like:

> type.foo = 9

To prevent this, we need to deny write access to the table. The trick to doing this is to use a metatable and set the __index and __newindex values.

So how does this work? When the user reads a value from the table (i.e. by using type.foo), Lua fails to find “foo” in the table. So it looks in the metatable for the __index key. If that is set to point to a table, then it will try to lookup the value in that table. In the case above, it finds the “foo” value and returns it like normal. However, if the user attempts to assign to type.foo, Lua follows the __newindex path, which causes a function to get called that does nothing but print an error… effectively, the write is denied. Here’s what happens:

> type.foo = 9
[string "?"]:1: Attempt to modify read-only table

Okay, cool… we’ve made read-only enumerations, but what about typing. Glad you asked! We add one more layer of abstraction, of course <groaning>:

Basically, we make each value a table that includes the actual value and a type (“type” in our example above). The check_enum_type() function looks at the “type” field in the table to make sure the correct type was passed to your function. The get_enum_value() function gets the “value” field… which is equal to the actual C-enum type you’d expect. From the Lua side, you can inspect the enums like:

> print(type.foo.value)
0
> print(type.foo.type)
type

Explicitly, “type” is a read-only table with value “foo”. The value of “foo” is the table { value=0, type="type" }. I hope this explanation helps. Obviously, I’ve been geeking out on Lua a little too much lately

Get IP address:
ifconfig eth0 | awk '/inet / {print $2}' | awk -F: '{print $2}‘

Get MAC address:
ifconfig eth0 | awk '/HWaddr/ {print $5}'

Get network gateway IP address:
route -n | awk '/^0.0.0.0/ {print $2}'

Here’s the mapping, taken from a Microsoft TechNet article:

To support IP multicasting, the Internet authorities have reserved the multicast address range of 01-00-5E-00-00-00 to 01-00-5E-7F-FF-FF for… media access control (MAC) addresses.

To map an IP multicast address to a MAC-layer multicast address, the low order 23 bits of the IP multicast address are mapped directly to the low order 23 bits in the MAC-layer multicast address. Because the first 4 bits of an IP multicast address are fixed according to the class D convention, there are 5 bits in the IP multicast address that do not map to the MAC-layer multicast address. Therefore, it is possible for a host to receive MAC-layer multicast packets for groups to which it does not belong. However, these packets are dropped by IP once the destination IP address is determined.

For example, the multicast address 224.192.16.1 becomes 01-00-5E-40-10-01.

Happy hacking!

There are many pages describing how to resample audio using the ffmpeg command line application, but what about doing resampling in your own program? To do that, you need to use the avcodec library (libavcodec.so on Linux and avcodec.dll on Windows).

1. Include avcodec.h
2. Call avcodec_init() to initialize the FFMpeg library.
3. Create a resampling context using av_resample_init() that describes how you want the resampling done.
4. Call av_resample() to do the actual resampling on your audio buffer.
5. When you’re done with the resampling context, delete it with av_resample_close().
6. Finally, link your application against avcodec, avutil, and zlib (it won’t work on Linux without this one).

Here it is in pseudocode:

#include "libavcodec/avcodec.h"

avcodec_init();

struct AVResampleContext* ctx = av_resample_init( ... );

av_resample( ctx, ... );

av_resample_close( ctx );

That’s it… seriously!

Sample Code (Linux):

Here’s a sample program I wrote that takes a raw 44.1kHz/16bit/mono audio file and plays it back using the pulseaudio API. The catch is that it allows you to specify a “skew” parameter which will cause the audio to dynamically speed up and slow down (via resampling). The amount of resampling is controlled by a sine wave, which is what drives the speed changes.

Download: resample.tar.bz

To unpack and build, type:

$ tar -xjvf resample.tar.bz
$ make

First, run the sample with no skew:

$ ./resample audio_16b_44k_mono_pcm_raw 0

Now, try it with a heavy skew:

$ ./resample audio_16b_44k_mono_pcm_raw -10000

For the thread “How VSync works, and why people loathe it“:

There is a technique called triple-buffering that solves this VSync problem. Lets go back to our 50FPS, 75Hz example. Frame 1 is in the frame buffer, and 2/3 of frame 2 are drawn in the back buffer. The refresh happens and frame 1 is grabbed for the first time. The last third of frame 2 are drawn in the back buffer, and the first third of frame 3 is drawn in the second back buffer (hence the term triple-buffering). The refresh happens, frame 1 is grabbed for the second time, and frame 2 is copied into the frame buffer and the first part of frame 3 into the back buffer. The last 2/3 of frame 3 are drawn in the back buffer, the refresh happens, frame 2 is grabbed for the first time, and frame 3 is copied to the frame buffer. The process starts over. This time we still got 2 frames, but in only 3 refresh cycles. That’s 2/3 of the refresh rate, which is 50FPS, exactly what we would have gotten without it. Triple-buffering essentially gives the video card someplace to keep doing work while it waits to transfer the back buffer to the frame buffer, so it doesn’t have to waste time. Unfortunately, triple-buffering isn’t available in every game, and in fact it isn’t too common. It also can cost a little performance to utilize, as it requires extra VRAM for the buffers, and time spent copying all of them around. However, triplebuffered VSync really is the key to the best experience as you eliminate tearing without the downsides of normal VSync (unless you consider the fact that your FPS is capped a downside… which is silly because you can’t see an FPS higher than your refresh anyway).

If the thread is ever unavailable, you can download a PDF version HERE.

ThreadNinja is a Linux library my team created that tracks pthread_create() and pthread_join() calls in an application. It prints a stacktrace where each thread is created and where it is joined. Any rogue (unjoined) threads are reported when the application exits. ThreadNinja is unobtrusive: it does NOT have to be compiled into the code. This means you can use it on applications you didn’t compile.

We found it useful and thought we’d share it. It’s be no means production code… just a tool. Hack on it, expand it, change it… whatever. It’s pretty small, so it should be easy to dive right in. We’ve released it under the BSD license.

Cut To The Chase

You can checkout the source code from Google Code, or download the version 1.0 tarball directly (threadninja.tar.gz).

To build ThreadNinja, simply untar it and call make:
> tar -zxf threadninja.tar.gz
> make

Now, simply use LD_PRELOAD to run the application:

> LD_PRELOAD=/path/to/threadninja/build/libthreadninja.so.1 TheApplication

If you don’t see function names in the stacktraces that are generated, then the application needs to be compiled with debug symbols. For my test app, I had to compile with the -rdynamic option:

> g++ -Wall -rdynamic main.cpp -lpthread

This causes the global symbol table to be included in the executable, which contains all the application’s function names. For more info, look at the --export-dynamic option on the GNU linker (ld) man page.

The Story Behind ThreadNinja

My team was assigned to stabilize a large video application that runs as a Linux-based appliance. The application consisted of 100,000+ of lines to code that was a tangle of build warnings, circular references, and many creative hacks. Our particular task was to fix a persistent set of seg-faults and memory leaks.

One of the first things we noticed was that the application didn’t shutdown properly. The shutdown logic was something akin to: signal components to exit, sleep 2 seconds, call Release() a couple times to clean up extra ref-counts, sleep 2 seconds, and then just call exit() to get the process to terminate (bypassing the remaining clean up code). Of course, this renders Valgrind useless when trying to find memory leaks, because the automatic memory cleanup code gets bypassed during the process abort.

As a result, our first priority was to get the app to shutdown cleanly. The first issue we ran into was that pthread_join() blocked indefinitely because threads were failing to terminate. We tried using GDB to track the threads, but many hundreds of threads were being created and destroyed dynamically. We needed a way to let the application run for hours, allow 1000+ threads to live and die, and still be able to track rogue threads. Hence, ThreadNinja was born.

How It Works

Through the magic of LD_PRELOAD, ThreadNinja “injects” itself between all calls to pthread_create() and pthread_join(). This happens because LD_PRELOAD instructs the loader to load ThreadNinja into memory first, before other libraries (in this case, before the pthread library). The result is that ThreadNinja’s implementation of pthread_create() and pthread_join() are used by the application instead of pthread’s own implementation. What ThreadNinja does is track the calls to these methods and then pass the call on to the “real” pthread implementation. From the application’s point-of-view, the behavior of the thread methods are the same… the tracking is transparent.

Output

Each time pthread_create() is called, a stacktrace and timestamp are printed to stdout:

Thread Created: 3047947120
[bt] Thu Jul 8 16:31:23 2010

[bt] ./a.out(StartService(unsigned long*, int))
[bt] ./a.out(Initialize())
[bt] ./a.out(main+0xb) [0x80489fa]
[bt] /lib/libc.so.6(__libc_start_main+0xe6) [0xb5bbb6]
[bt] ./a.out() [0x8048811]

The first line (“Thread Created”) gives the value of the pthread_t handle, so you can later track where rogue threads where created. The next line is the time when the create happened. The remaining lines are the call stack that led to the pthread_create() call.

Each time pthread_join() is called, similar information is printed to stdout:

Thread Joined: 3047947120
[bt] Thu Jul 8 16:31:31 2010

[bt] ./a.out(Terminate())
[bt] ./a.out(main+0x10) [0x80489ff]
[bt] /lib/libc.so.6(__libc_start_main+0xe6) [0xb5bbb6]
[bt] ./a.out() [0x8048811]

When the application terminates (cleanly or uncleanly), a summary of the current state of the application threads is printed:

exit_handler()
[Thread Summary]
Total Created: 573
Total Joined: 568
Total Running: 5

In this case, you’ll notice that 5 threads were never joined on.

Limitations

ThreadNinja only tracks calls to pthread_create() and pthread_join(). This means calls like system(), exec(), and fork() are not tracked. Also, calls to pthread_cancel() are not tracked. We had started adding code to track pthread mutexes and stuff, but it turned out we didn’t need it. Feel free to add support for all this stuff and submit changes to the Google code site.

Happy coding!

Note: I’m talking here about interval timing (i.e. accurately measuring the duration between 2 events). This is different than synchronizing different clocks or maintaining accurate wall time.

Anatomy of the Clock

The first mistake most people make when doing timing is to use functions like gettimeofday(), GetSystemTime(), etc. These functions return what is called “wall time”… time that corresponds to a calendar date/time. These clocks suffer from the follow limitations:

1. They have a low resolution: “High-performance” timing, by my definition, requires clock resolutions into the microseconds or better.
2. They can jump forwards and backwards in time: Computer clocks all tick at slightly different rates, which causes the time to drift. Most systems have NTP enabled which periodically adjusts the system clock to keep them in sync with “actual” time. The adjustment can cause the clock to suddenly jump forward (artificially inflating your timing numbers) or jump backwards (causing your timing calculations to go negative or hugely positive).

For interval timing, all that’s needed for a clock is a simple counter that increments at a stable rate. For high-performance timing, the rate this counter increments should be high. A related constraint is that the counter must be monotonic (can never “tick” backwards… ever). The counter may overflow and wrap back to 0, but using unsigned math in your timing calculations can compensate for that (see example below).

Something to note: since we are usually measuring short durations, the drift of the clock is so small that we aren’t concerned by it (what matters is the drift between successive reads, not total drift over time).

Using the Clock

To use the clock, you need access to 2 pieces of information: the clock value, and the rate (frequency) at which it increments. Once you have that information, it’s trivial to calculate the duration between 2 successive reads of the clock.

For example, consider the following:

-        start equals the clock value at the beginning of the interval to measure.

-        end equals the clock value at the end of the interval.

-        frequency equals the frequency that the clock increments per second.

Calculating the duration of the interval (in seconds) is as simple as:

duration = (end – start) / frequency

duration will equal the floating-point interval time in seconds (e.g. 0.000237 = 237us).

A common use case I’ve seen is wanting to measure the duration between successive calls to a function. Here’s one way to implement that:

float freq = (float) get_frequency();

Foo()
{
    unsigned now = read_clock();
    float duration = (float)(now – last) / (float)freq;
    last = now;

    /* Your code here */
}

It is important to use unsigned variables for now and last or your calculations will go haywire if the clock ever wraps back to 0. Consider what happens if now is less than last. Using unsigned variables allows the math operation to underflow, which produces the correct result. If you don’t believe me, just write some test code and see for yourself… it’s an important concept to understand.

Don’t Use RDTSC As Your Clock

I’m dismayed by how many forum posts suggest that newbie’s use RDTSC for timing. Don’t get me wrong; the TSC isn’t bad in-and-of-itself. It’s just way too hard to get timing right with it unless you’re an expert… and if you’re reading this, chances are you aren’t . Stick to the higher level API’s I present below.

Even if you are an expert, I still suggest avoiding RDTSC for the following reasons:

1. It’s processor core specific: Using RDTSC will give different values on different processor cores. This causes non-monotonic clock behavior as a thread is migrated across cores during execution (i.e. the clock can tick backwards on two successive reads). Conversely, the clock may also appear to jump forwards if the thread moves to a different core.
2. It doesn’t always tick at the same rate: On some systems, the clock frequency will vary as the CPU load changes. This is due to power saving features in the processor that throttle down the clock speed when the load is low (e.g. Intel SpeedStep).
3. It’s unnecessary: there are better alternatives to RDTSC that are readily available (HPET and APIC).

“Game Timing and Multicore Processors” has more info, though it’s centered around Windows.

“Guidelines For Providing Multimedia Support” has a good summary of the hardware clocks on the PC platform, and justification for the creation of the HPET.

A more technical look into the past problems with RDTSC can be found in this email from Rick Brunner (AMD Fellow).

If you’re having trouble sleeping, you can look at Intel’s HPET design document.

Linux Clock

POSIX.1b defines realtime clock methods that you’ll find on most *NIX systems (the full spec can be viewed HERE). Specifically, you want to use clock_getres() and clock_gettime(). clock_getres() returns the resolution (frequency) of the clock, and clock_gettime() returns the current value of the clock. Most systems implement the CLOCK_MONOTONIC type, which provides a frequency-stable, monotonically-increasing counter. The resolution of CLOCK_MONOTONIC is high on the 2.6 kernel, in my experience. I recommend using this clock when building a high-performance timing solutions on Linux.

The methods are defined in time.h, and you need to link against librt (pass ‘-lrt’ to gcc). The prototypes for the functions are:

int clock_getres(clockid_t clock_id, struct timespec *res);
int clock_gettime(clockid_t clock_id, struct timespec *tp);

A detailed description of these methods can be found HERE.

I also suggest looking at clock_nanosleep(), but that’s a separate topic.

Windows Clock

On Windows, QueryPerformanceFrequency() and QueryPerformanceCounter() are the obvious choice. QueryPerformanceFrequency() returns (surprise!) the frequency of the counter. QueryPerformanceCounter() returns the current value of the counter. Just like CLOCK_MONOTONIC on Linux, the Windows performance counter is a high-frequency, stable, monotonically-increasing counter.

The methods are defined in windows.h. The prototypes are:

BOOL QueryPerformanceFrequency(LARGE_INTEGER *lpFrequency);
BOOL QueryPerformanceCounter(LARGE_INTEGER *lpPerformanceCount);

Windows Timing Errata

Note: The follow items do NOT affect the resolution of the Window’s performance counter, but I think it’s still important to know when doing timing on Windows.

One problem you may run into on Windows is that the default system clock interval defaults to 10 or 15ms (depending of the OS version). This clock is what drives all the timers and sleep functions for that platform. What this means is that, left to the default, your timers will trigger 5 to 7.5ms late, on average.

You can fix this by increasing the system clock resolution to 2ms (I remember reading a tech article by Microsoft saying that 2ms gave better system performance than 1ms, but I can’t find it for the life of me). You do this by using the timeGetDevCaps(), timeBeginPeriod() and timeEndPeriod(). Sample code can be found HERE. You have to include mmsystem.h and link against Winmm.lib.

I feel it necessary to note that increasing the system clock interval negatively affects power consumption. The Windows 7 blog as an interesting breakdown of “Windows 7 Energy Efficiency”. Specifically, they noticed a 10% drop in battery life when the clock resolution was set to 1ms using timeBeginPeriod().

Maybe this last section belongs in a separate post, but whatever…

Example

Consider the following log method:

void WriteLog( const LOG_LEVEL level, const char* file, const int line, const char* format, ... );

Pretty straight-forward: it allows you to specify the log level (NOTICE, WARNING, ERROR, etc), a file name and line number, and a user-defined description in “printf” format. To log a warning message, you would type:

WriteLog( LL_WARNING, __FILE__, __LINE__, "[WARNING] Failed to import descriptor '%s:%i'!", _descriptor, _id );

The entry in the log file would look like:

Core.cpp:715 [WARNING] Failed to import descriptor 'timing-engine'!

Creating a Variadic Macro

Calling WriteLog directly works fine, but it’s pretty verbose and annoying to use. One way to make it simpler is to wrap WriteLog with a variadic macro:

#define LOG_WARNING( format, ... ) \\
WriteLog( LL_WARNING, __FILE__, __LINE__, "[WARNING] " format, ##__VA_ARGS__ );

Then the example above would become:

LOG_WARNING( "Failed to import descriptor '%s:%i'!", _descriptor, _id );

The macro automatically fills in the file and line number where the log message was generated, and the log level is specified by the macro name (LOG_WARNING). This is much more straight-forward and I believe it makes the code easier to read.

Notice that __VA_ARGS__ is used to get the variable argument list and pass it to WriteLog. During compilation, the preprocessor replaces __VA_ARGS__ with the comma-separated list of  arguments. The ‘##‘ that prefixes __VA_ARGS__ is vital if you want your macro to work like you expect. Without it, you would be required to have at least one argument after the format string. ’##‘ has a special meaning in this case: it causes the preceding comma to be deleted if there are no variable arguments. Without this, the following line would generate a syntax error:

LOG_WARNING( "This would cause a syntax error" );

Prefixing __VA_ARGS__ with ‘##‘ allows the above code to work just fine.

Looking at the logs, we found that our audio pipeline was failing to open /dev/dsp on the restart. We then used lsof to list the open file descriptors to see which process currently held /dev/dsp:

# lsof | grep /dev/dsp
ntpd   18857    root   16u    CHR     14,3    180099 /dev/dsp


What!?!?… why the heck is NTP opening the sound device and how did it steal it from us??? After some discussion we started remembering a problem in the past with ntpd stealing our SNMP diagnostics port. This just didn’t make any sense.

Digging into our appliance code, we found this line:

system( "service ntpd restart" );

This would be called each time we were notified by the security system that the NTP server address had changed (which fired once each time the process was started so we could get the initial address). But this still didn’t explain why NTP took over ownership of our file descriptors on restart.

Long story short: system() is implemented as fork() followed by execv(). By default, fork() gives a copy of the parent’s file descriptors to the child process (i.e. the ntpd child process got a copy of the /dev/dsp file descriptor). To prevent this, you have to set the FD_CLOEXEC flag on the file desciptors you don’t want copied.

For example:

fd = open( "/dev/dsp", O_RDWR );
fcntl( fd, F_SETFD, FD_CLOEXEC );

Conclusion: setting the FD_CLOEXEC flag on the /dev/dsp file descriptor fixed the problem for audio. However, most of the other file desciptors still got owned by ntpd. Did we go back and set the FD_CLOEXEC flag on all file descriptors, you ask? Nope. It turns out we had a script monitoring the NTP config file and restarting ntpd for us when the file got updated… we just had to update the config file and remove the system( "service ntpd restart" ) call.

Oh, and the reason audio worked on first boot but not subsequent restarts was due to a weird race condition around when /dev/dsp got opened.