A number of (as yet incomplete) documents attempt to describe the API for writing modules:

- http://pike.ida.liu.se/projects/docs/cmods/

• http://www.gotpike.org/files/cmodules-jg.pdf
• http://www.gotpike.org/files/cmodules-grendel.pdf
• http://pike.ida.liu.se/development/cvs/browse.xml (look in Pike/0.5/doc)
• alephOneTutorial

  - http://hww3.riverweb.com/space/pike/development tips has some notes about module development.

  However, it is often simpler to look at existing code for clues.

  The following document provides information about the Pike module build system, and how to create new modules using it: Pike Module Build System

  A stub module is available from Bill Welliver's HG Repo . This makes a nice starting point for "monger compliant" modules written either in Pike or C/CMOD.

  Testsuites

  Info about Writing Testsuites.

  Data Structures

  - svalue

• Pike_fp
• type_field
• Pike_sp

  Methods

• check_svalue
• check_refs
• add_ref
• sub_ref
• swap_values_unlocked
• MAKE_CONST_STRING
• array_free_index
• make_shared_string

  Topics

  # how to allocate a string from C using Pike API

1. how to create an array/mapping
2. how to create an object deriving it from some class
3. how to check whether an object passed to a function has a method you want to call
4. how to set up a callback from C code
5. how to invoke a standalone Pike function from C code: see Calling Pike Code
6. how to invoke an object method from C code
7. how to pass parameters to a Pike function
8. how to retrieve the return value of the Pike function
9. how is the Pike stack organized: see Pike_sp
10. what are the possible parameters to the ADD_FUNCTION API
11. what are the type contstants C code can use
12. what are svalues and how do you use them
13. how to allocate module-specific storage area
14. error handling

    Module (ie, Java "static") methods in a CMOD

    You can have INIT, EXIT and PIKEFUN blocks outside of a PIKECLASS directive. Because modules are already instantiated as objects, this allows your module to have functions as well as classes.

    Working with references

    Pike utilizes garbage collection and reference counting to handle memory management of pike data objects (strings, arrays, objects, etc). When writing C/CMOD code, you need to tell pike that you explicitly want to keep data around once it passes out of your function, along with the corresponding process of telling pike that you're done with the object afterward. Pike provides methods for doing this (though some methods will add references automatically).

    add_ref(svalue val) is used to add a reference to a variable.

    free_string(pike_string val) and its corresponding friends is used to subtract references and will free the variable if there are no more references to that variable. The name can be confusing but it's best to think of it from the standpoint of your code not knowing whether other code is using your variable. You're just saying that "it's ok by me if you want to free this value." Pike will actually do that when everone who said they wanted to keep it no longer want the value.

    Looping through Mappings

   INT32 e;
    struct keypair *k;
    NEW_MAPPING_LOOP(mapping->data) {
       k->ind  
       k->val  // both are svalues
    }

To lookup a string index in a mapping, use the following:

struct svalue *sv;
struct mapping *m;
sv=simple_mapping_string_lookup(m,"name");

This returns the svalue corresponding to the index "name" in the mapping m.

Declaring a new class

This snippet shows the basics of declaration of a new class.

void pike_module_init(void)
{
...
start_new_program();
low_inherit(myparent_program, 0,0,0,0,0);
ADD_STORAGE(myclass_storage);
set_exit_callback( myclass_exit_callback );
ADD_FUNCTION("create", f_myclass__create,tFunc( tInt tInt,tVoid), 0);
add_program_constant("MyClass", (myclass_program=end_program()), 0);
...

Powered by PikeWiki2