Chapter 17, Pike internals - how to extend Pike

program cast_to_program(string program_name, string current_file)

This function is called whenever someone performs a cast from a string to a program.

program handle_inherit(string program_name, string current_file)

This is called whenever a Pike program which uses inherit with a string argument is called. It is expected to return the program to inherit.

void handle_error(array trace)

This function is expected to write the error messages when a run time error occurs. The argument is of the form ({"error_description", backtrace() }). If any error occurs in this routine Pike will dump core.

program cast_to_program(string program_name, string current_file)

This function is called whenever someone performs a cast from a string to an object.

mixed resolv(string identifier, string current_file)

This function is called whenever the compiler finds an unknown identifier in a program. It is normally used for loading modules. It is supposed to return ([])[0] if the master doesn't know what the value should be, and the value in question otherwise.

void _main(array(string) argv, array(string) env)

This function is supposed to start a Pike script. It receives all the command line arguments in the first array and all environment variables on the form "var=value". _main is called as soon as all modules and setup is done.

void compile_error(string file, int line, string err)

This function is called whenever a compile error is encountered. Normally it just writes a message to stderr.

string handle_include(string file, string current_file, int local_include)

This function is used to locate include files. file is the file name the user wants to include, and local_include is 1 if the user used double quotes rather than lesser-than, greater-than to quote the file name. Otherwise it is zero.

Aside from the above functions, which are expected from the Pike binary, the master object is also expected to provide functions used by Pike scripts. The current master object adds the following global functions:

add_include_path, remove_include_path, add_module_path, remove_module_path, add_program_path, remove_program_path, master, describe_backtrace, mkmultiset, strlen, new, clone, UNDEFINED, write, getenv and putenv.

There are at least two ways to change the behavior of the master object. (Except for editing it directly, which would cause other Pike scripts not to run in most cases.) You can either copy the master object, modify it and use the command line option -m to load your file instead of the default master object. However, since there might be more functionality added to the master object in the future I do not recommend this.

A better way is to write an object that inherits the master and then calls replace_master with the new object as argument. This should be far more future-safe. Although I can not guarantee that the interface between Pike and the master object will not change in the future, so be careful if you do this.

Let's look an example:

#!/usr/local/bin/pike

class new_master {
    inherit "/master";

    void create()
    {
        /* You need to copy the values from the old master to the new */
        /* NOTE: At this point we are still using the old master */
        object old_master = master();
        object new_master = this_object();
 
        foreach(indices(old_master), string varname)
        {
            /* The catch is needed since we can't assign constants */
            catch { new_master[varname] = old_master[varname]; };
        }
    }

    void handle_error(array trace)
    {
        Stdio.write_file("error log",describe_backtrace(trace));
    }
};

int main(int argc, array(string) argv)
{
    replace_master(new_master());
    /* Run rest of program */
    exit(0);
}

17.2 Data types from the inside

17.2.1 Basic data types

17.2.2 struct svalue

17.2.3 struct pike_string

A struct pike_string has these members:

INT32 refs;

The references to this string.

INT32 length;

This is the length of the string.

unsigned INT32 hval;

This is the internal hash value for the string, you should not have to use this member for any reason.

struct pike_string *next;

This points to the next string in the hash table. Internal use only.

int size_shift;

This represents the size of the characters in the string. Currently size_shift has three valid values: 0, 1 and 2. These values mean that the characters in the string are 1, 2 and 4 bytes long respectively.

char str[1];

This is the actual data. Note that you should never use this member directly. Use STR0, STR1 and STR2 instead.

General string management

FUNCTION

STR0 - Get a pointer to a 'char'

SYNTAX

p_wchar0 *STR0(struct pike_string *s);
p_wchar1 *STR1(struct pike_string *s);
p_wchar2 *STR2(struct pike_string *s);

DESCRIPTION

These macros return raw C pointers to the data in the string s. Note that you may only use STR0 on strings where size_shift is 0, STR1 on strings where size_shift is 1 and STR2on strings where size_shift is 2. When compiled with DEBUG these macros will call fatal if used on strings with the wrong size_shift.

NOTE

All pike strings have been zero-terminated for your convenience.
The zero-termination is not included in the length of the string.

FUNCTION

free_string - Free a reference to a pike_string

SYNTAX

void free_string(struct pike_string *s);

DESCRIPTION

This function frees one reference to a pike string and if that is the last reference, it will free the string itself. As with all refcounting functions you should be careful about how you use it. If you forget to call this when you should, a memory leak will occur. If you call this function when you shouldn't Pike will most likely crash.

17.2.4 struct array

A struct array has these members:

FUNCTION

allocate_array

FUNCTION

free_array

FUNCTION

array_index

FUNCTION

array_index_no_free

FUNCTION

simple_array_index_no_free

FUNCTION

array_set_index

FUNCTION

push_array_items

FUNCTION

aggregate_array

FUNCTION

f_aggregate_array

FUNCTION

append_array

FUNCTION

explode

FUNCTION

slice_array

FUNCTION

add_arrays

FUNCTION

copy_array

17.2.5 struct mapping

This is the contents of a struct mapping:

FUNCTION

m_sizeof

FUNCTION

m_ind_types

FUNCTION

m_val_types

FUNCTION

MAPPING_LOOP

FUNCTION

free_mapping

FUNCTION

allocate_mapping

FUNCTION

mapping_insert

FUNCTION

mapping_get_item_ptr

FUNCTION

map_delete

FUNCTION

low_mapping_lookup

FUNCTION

low_mapping_string_lookup

FUNCTION

simple_mapping_string_lookup

FUNCTION

mapping_string_insert

FUNCTION

mapping_indices

FUNCTION

mapping_values

FUNCTION

mapping_to_array

FUNCTION

mapping_replace

FUNCTION

mkmapping

FUNCTION

copy_mapping

17.2.6 struct object

17.2.7 struct program

17.3 The interpreter

• The stack
• The frame pointer
• {ref_}push_*