C Modules

[ Start > PikeDevel > C Modules ] [ Edit this Page | Show Page Versions | Show Formatted ]

Creating extensions to the Pike language is a fairly simple task. Extensions can be written in C or C++, and may be hand coded or written using a preprocessed version of C called [PikeDevel/C Modules/CMOD]. CMOD simplifies the writing of C language modules by providing a number of simplifications, such as automatic handling of method and class registrations, argument handling and so forth. There are a number of limitations to the CMOD preprocessor, but for the majority of extensions, CMOD will work just fine.

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
- {link:http://pike.ida.liu.se/development/cvs/browse.xml} (look in Pike/0.5/doc)
- [PikeDevel/C Modules/alephOneTutorial] 

- {link: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: {link:Pike Module Build System|http://modules.gotpike.org/docs/PikeModule.html}

A stub module is available from {link:Bill Welliver's HG Repo|http://hg.welliver.org/pike_modules-samplemodule} . This makes a nice starting point for "monger compliant" modules written either in Pike or C/CMOD. 


Info about [PikeDevel/Writing Testsuites].

__Data Structures__

- [PikeDevel/C Modules/svalue]
- [PikeDevel/C Modules/Pike_fp]
- [PikeDevel/C Modules/type_field]
- [PikeDevel/C Modules/Pike_sp]

    *  check_svalue
    * check_refs
    * add_ref
    * sub_ref
    * swap_values_unlocked
    * array_free_index
    * [PikeDevel/C Modules/make_shared_string]


#  how to allocate a string from C using Pike API
# how to create an array/mapping
# how to create an object deriving it from some class
# how to check whether an object passed to a function has a method you want to call
# how to set up a callback from C code
# how to invoke a standalone Pike function from C code: see [PikeDevel/C Modules/Calling Pike Code]
# how to invoke an object method from C code
# how to pass parameters to a Pike function
# how to retrieve the return value of the Pike function
# how is the Pike stack organized: see [PikeDevel/C Modules/Pike_sp]
# what are the possible parameters to the ADD_FUNCTION API
# what are the type contstants C code can use
# what are svalues and how do you use them
# how to allocate module-specific storage area
# [PikeDevel/C Modules/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__

The __NEW_MAPPING_LOOP__ macro allows you to loop through all elements in a mapping. Note that the keypair name (~~k~~) is required and is hard coded.


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

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

struct svalue *sv;
struct mapping *m;

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)
low_inherit(myparent_program, 0,0,0,0,0);
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

gotpike.org | Copyright © 2004 - 2009 | Pike is a trademark of Department of Computer and Information Science, Linköping University