Without CMOD

Let us assume we want to write a new C module and that a Pike level design of that module already has been done. Let us also assume we want to do it the old fashion way and not use CMOD. As mentioned in the section above we need to define our Pike level interface. The question is how is that done? The keyword here, if we are not using CMOD, is the pike_module_init() function. Even though it might not be entirely correct from a technical point of view, we can say that the whole module with all classes and methods is defined in this function. The sequence chart in figure 5.1 illustrates what happens when a module is initialized. As it can be seen in the chart the initialization is so to speak the definition of the Pike level interface since each component in the module is added here.

To add a class start_new_program() and end_class() calls are placed in the pike_module_init() function. These two calls when used together add an empty class to the module.

If we want to add a method to that empty class we use the macro ADD_FUNCTION(). We place the call to ADD_FUNCTION() somewhere in between the calls to start_new_program() and end_class() of the class that we want the method to belong to.

To add private object variables the macro ADD_STORAGE() is useful. Variables that need to be kept in a storage, are those that need to be 'remembered' over several function calls. In other words, variables that in some way represent the inner state of an object need to be kept in storage. To add storage to a class we need to place a call to ADD_STORAGE() somewhere in between the call to start_new_program() and the call to end_class() of the class that we want the storage to belong to. The first call to ADD_STORAGE() after a call to start_new_program() will yield a handle. Storages added by other calls will lie within an offset of this storage. The module programmer will have to keep track of that offset manually if he chooses to add more than one storage. Therefore, an easy way to handle multiple object variables without adding more than one storage is to pack them all into one struct on the C level. Then this struct is made the first and only added storage of the class. Every object variable can then be accessed using the Pike_fp-current_storage pointer. So in order to add all private object variables, we first create a struct that contains all the variables needed. Then place a call to ADD_STORAGE() with that struct as only argument, somewhere in between the corresponding start_new_program() and end_class() .

Last in each definition of a class we need to set the initialization and exit callbacks. The init callback is set by adding a call to set_init_callback(). The exit callback is set by adding a call to set_exit_callback().

In order for the now defined Pike level interface to compile, stubs for the functions that will be written later on, have to be added. All C functions that represent the implementation of a Pike method need to look like this:

   static void function_name(INT32 args).

That is just the way the C API works. If we have defined a method (using ADD_FUNCTION()) that is specified to be implemented by the C function function_name(), a function like the one just mentioned will be requested.

Further all functions that have been set as init- or exit callback also need to exist to make the Pike level interface compile.