Welcome to the World of Knowledge and Fun...: 05/22/08

What Is a Callback Function?
The simple answer to this first question is that a callback function is a function that is called through a function pointer.
If you pass the pointer (address) of a function as an argument to another, when that pointer is used to call the function
it points to it is said that a call back is made.

Why Should You Use Callback Functions?
Because they uncouple the caller from the callee. The caller doesn't care who the callee is; all it knows is that there
is a callee with a certain prototype and probably some restriction (for instance, the returned value can be int,
but certain values have certain meanings).

If you are wondering how is that useful in practice, imagine that you want to write a library that provides implementation
for sorting algorithms (yes, that is pretty classic), such as bubble sort, shell short, shake sort, quick sort, and others.
The catch is that you don't want to embed the sorting logic (which of two elements goes first in an array) into your functions,
making your library more general to use. You want the client to be responsible to that kind of logic. Or, you want it to be used
for various data types (ints, floats, strings, and so on). So, how do you do it? You use function pointers and make callbacks.

A callback can be used for notifications. For instance, you need to set a timer in your application.
Each time the timer expires, your application must be notified. But, the implementer of the time'rs mechanism doesn't know
anything about your application. It only wants a pointer to a function with a given prototype, and in using that pointer it
makes a callback, notifying your application about the event that has occurred. Indeed, the SetTimer() WinAPI uses a callback
function to notify that the timer has expired (and, in case there is no callback function provided, it posts a message to the
application's queue).

Another example from WinAPI functions that use callback mechanism is EnumWindow(), which enumerates all the top-level windows
on the screen. EnumWindow() iterates over the top-level windows, calling an application-provided function for each window,
passing the handler of the window. If the callee returns a value, the iteration continues; otherwise, it stops.
EnumWindows() just doesn't care where the callee is and what it does with the handler it passes over.
It is only interested in the return value, because based on that it continues its execution or not.

However, callback functions are inherited from C. Thus, in C++, they should be only used for interfacing C code and existing
callback interfaces. Except for these situations, you should use virtual methods or functors, not callback functions.

A Simple Implementation Example

Now, follow the example that can be found in the attached files. I have created a dynamic linked library called sort.dll. It exports a type called CompareFunction:

typedef int (__stdcall *CompareFunction)(const byte*, const byte*);

which will be the type of your callback functions. It also exports two methods, called Bubblesort() and Quicksort(), which have the same prototype but provide different behavior by implementing the sorting algorithms with the same name.

void DLLDIR __stdcall Bubblesort(byte* array,
                                int size,
                                int elem_size,
                                CompareFunction cmpFunc);

void DLLDIR __stdcall Quicksort(byte* array,
                               int size,
                               int elem_size,
                               CompareFunction cmpFunc);

These two functions take the following parameters:

byte* array: a pointer to an array of elements (doesn't matter of which type)
int size: the number of elements in the array
int elem_size: the size, in bytes, of an element of the array
CompareFunction cmpFunc: a pointer to a callback function with the prototype listed above

The implementation of these two functions performs a sorting of the array. But, each time there is a need to decide which of two elements goes first, a callback is made to the function whose address was passed as an argument. For the library writer, it doesn't matter where that function is implemented, or how it is implemented. All that matters it is that it takes the address of two elements (that are the two be compared) and it returns one of the following values (this is a contract between the library developers and its clients):

-1: if the first element is lesser and/or should go before the second element (in a sorted array)
0: if the two elements are equal and/or their relative position doesn't matter (each one can go before the other in a sorted array)
1: if the first element is greater and/or should go after the second element (in a sorted array)

With this contract explicitly stated, the implementation of the Bubblesort() function is this (for Quicksort(), which a little bit more complicated, see the attached files).

void DLLDIR __stdcall Bubblesort(byte* array,
                                int size,
                                int elem_size,
                                CompareFunction cmpFunc)
{
  for(int i=0; i < size; i++)
  {
     for(int j=0; j < size-1; j++)
     {
        // make the callback to the comparison function
        if(1 == (*cmpFunc)(array+j*elem_size,
                 array+(j+1)*elem_size))
        {
           // the two compared elements must be interchanged
           byte* temp = new byte[elem_size];
           memcpy(temp, array+j*elem_size, elem_size);
           memcpy(array+j*elem_size,
                  array+(j+1)*elem_size,
                  elem_size);
           memcpy(array+(j+1)*elem_size, temp, elem_size);
           delete [] temp;
        }
     }
  }
}

Note: Because the implementation uses memcpy(), these library functions should not be used for types other than POD (Plain-Old-Data).

On the client side, there must be a callback function whose address is to be passed to the Bubblesort() function. As a simple example, I have written a function that compares two integer values and one that compares two strings:

int __stdcall CompareInts(const byte* velem1, const byte* velem2)
{
  int elem1 = *(int*)velem1;
  int elem2 = *(int*)velem2;

  if(elem1 < elem2)
     return -1;
  if(elem1 > elem2)
     return 1;

  return 0;
}

int __stdcall CompareStrings(const byte* velem1, const byte* velem2)
{
  const char* elem1 = (char*)velem1;
  const char* elem2 = (char*)velem2;

  return strcmp(elem1, elem2);
}

To put all these to a test, I have written this short program. It passes an array with five elements to Bubblesort() or Quicksort() along with the pointer to the callback functions.

int main(int argc, char* argv[])
{
  int i;
  int array[] = {5432, 4321, 3210, 2109, 1098};

  cout << "Before sorting ints with Bubblesort\n";
  for(i=0; i < 5; i++)
     cout << array[i] << '\n';

  Bubblesort((byte*)array, 5, sizeof(array[0]), &CompareInts);

  cout << "After the sorting\n";
  for(i=0; i < 5; i++)
     cout << array[i] << '\n';

  const char str[5][10] = {"estella",
                           "danielle",
                           "crissy",
                           "bo",
                           "angie"};

  cout << "Before sorting strings with Quicksort\n";
  for(i=0; i < 5; i++)
     cout << str[i] << '\n';

  Quicksort((byte*)str, 5, 10, &CompareStrings);

  cout << "After the sorting\n";
  for(i=0; i < 5; i++)
     cout << str[i] << '\n';

  return 0;
}