Question

I’m going through a tutorial on audio for the iphone and it uses C/C++. I’m not familiar with the use of THIS->. It seems to refer to a pointer to global variable. Here is the tutorial – iPhone Core Audio Part 3 – Audio Callback.

The statement I am trying to understand is the THIS-> part of the statement:

// Pass in a reference to the phase value, you have to keep track of this
// so that the sin resumes right where the last call left off
float phase = THIS->sinPhase;

The tutorial indicate that THIS-> is used to get a to access AudioController variables. It seems that sinPhase is global variable.

Please explain why “phase” reference is created instead of just referring directly to the global variable “sinPhase”. Keep in mind I am an objective C programming trying to understand this C/C++ code.

Answer 1

In this example, THIS is not a reference to a global variable; it is defined above in the function, as a cast of the void pointer inRefCon:

static OSStatus renderInput(void *inRefCon, AudioUnitRenderActionFlags *ioActionFlags, const AudioTimeStamp *inTimeStamp, UInt32 inBusNumber, UInt32 inNumberFrames, AudioBufferList *ioData)
{
    // Get a reference to the object that was passed with the callback
    // In this case, the AudioController passed itself so
    // that you can access its data.
    AudioController *THIS = (AudioController*)inRefCon;

This is a fairly common pattern in C; in order to pass a callback in to some API, so that it can later call your code, you pass both a function pointer and a void pointer. The void pointer contains whatever data your function pointer will need to operate on. Within your callback, you will need to cast it back to a pointer to the actual type, so you can access the data within it. In this case, the author of the example is naming that cast pointer THIS, probably to make this look more object-oriented, even though this is just C and THIS has no special meaning.

You ask why they assign it to a local variable rather than just using THIS->sinPhase everywhere. There’s no reason you couldn’t use THIS->sinPhase everywhere; they likely just assigned it to a local variable phase to save on typing. There’s a small chance that the optimizer could do a better job on a local variable than on one passed in via a pointer, because it can make more assumptions about the local variable (in particular, it can assume that no one else is updating it at the same time). So the loop might run slightly faster using a local variable, though I wouldn’t be certain without testing; the most likely reason is just to save typing and make the code more readable.

Here’s a simplified example of how a callback API like this works; hopefully this should make it easier to understand how a callback API works, without trying to understand the rest of what’s going on in Core Audio at the same time. Let’s say I want to write a function that will apply a callback to an integer 10 times. I might write:

int do_ten_times(int input, int (*callback)(int)) {
    int value = input;
    for (int i = 0; i < 10; ++i) {
        value = callback(value);
    }
    return value;
}

Now I could call this with different functions, like the following add_one() or times_two():

int add_one(int x) {
    return x + 1;
}

int times_two(int x) {
    return x * 2;
}

result = do_ten_times(1, add_one);
result = do_ten_times(1, times_two);

But say I want to be able to add or multiply by different numbers; I could try writing one function for each number that you wanted to add or multiply by, but then you would run into a problem if the number wasn’t fixed in the code, but was based on input. You can’t write one function for each possible number; you are going to need to pass a value in. So let’s add a value to our callbacks, and have do_ten_times() pass that value in:

int do_ten_times(int input, int (*callback)(int, int), int data) {
    int value = input;
    for (int i = 0; i < 10; ++i) {
        value = callback(value, data);
    }
    return value;
}

int add(int x, int increment) {
    return x + increment;
}

int times(int x, int multiplier) {
    return x * multiplier;
}

result = do_ten_times(1, add, 3);
result = do_ten_times(1, times, 4);

But what if someone wants to write a function that varies by something other than an integer? For instance, what if you want to write a function that will add different numbers depending on whether the input is negative or positive? Now we need to pass two values in. Again, we could extend our interface to pass in two values; but we will eventually need to pass in more values, values of different types, and the like. We notice that do_ten_times really doesn’t care about the type of the value we’re passing in; it just needs to pass it to the callback, and the callback can interpret it however it likes. We can achieve this with a void pointer; the callback then casts that void pointer to the appropriate type to get the value out:

int do_ten_times(int input, int (*callback)(int, void *), void *data) {
    int value = input;
    for (int i = 0; i < 10; ++i) {
        value = callback(value, data);
    }
    return value;
}

int add(int x, void *data) {
    int increment = *(int *)data;
    return x + increment;
}

int times(int x, void *data) {
    int multiplier = *(int *)data;
    return x * multiplier;
}

struct pos_neg {
    int pos;
    int neg;
};
int add_pos_neg(int x, void *data) {
    struct pos_neg *increments = (struct pos_neg *)data;
    if (x >= 0)
        return x + increments->pos;
    else
        return x + increments->neg;
}

int i = 3;
result = do_ten_times(1, add, &i);
int m = 4;
result = do_ten_times(1, times, &m);
struct pos_neg pn = { 2, -2 };
result = do_ten_times(-1, add_pos_neg, &pn);

These are all, of course, toy examples. In the Core Audio case, the callback is used to generate a buffer of audio data; it is called every time the audio system needs to generate more data in order to keep playing smoothly. The information passed via the void *inRefCon is used to track how exactly where in the sine wave you have gotten to in the current buffer, so the next buffer can pick up where the last one left off.