embed.pod - Parrot embedding system
#include "parrot/embed.h" int main(int argc, char *argv[]) { Parrot_Interp interp; Parrot_PackFile pf; char *bcfile="program.pbc"; argc--; argv++; /* skip the program name */ interp=Parrot_new(NULL); Parrot_init(interp); if(PARROT_JIT_CAPABLE) { Parrot_setflags(interp, PARROT_JIT_FLAG, NULL); /* activate JIT */ } pf=Parrot_readbc(interp, bcfile); Parrot_loadbc(interp, pf); Parrot_runcode(interp, argc, argv); /* argc and argv as seen by the bytecode file */ Parrot_destroy(interp); return 0; }
Parrot's embedding system is designed with one guiding principle in mind: encapsulation. Users of Parrot shouldn't have to know what the insides of a Parrot_Interp structure look like or how to load a packfile. They should just know a few functions and constants. The embedding system is designed to do just that.
Parrot_Interp
This typedef represents (a pointer to) an actual Parrot interpreter.
Parrot_PackFile
This structure represents (a pointer to) a 'packfile'--a Parrot bytecode file.
Parrot_Interp_flag
An interpreter flag.
Parrot_Interp_flag_val
The value passed in with an interpreter flag. Unused at the moment--just pass in NULL.
NULL
Parrot_Int
Parrot_UInt
Parrot_Float
Parrot_Opcode
Various Parrot internal types; most are chosen at Configure time.
Interpreter flags:
PARROT_DEBUG_FLAG
This flag turns on debugging mode. Debugging mode basically means that Parrot's core prints out diagnostic messages. This flag does not take any parameters.
PARROT_TRACE_FLAG
This flag turns on opcode tracing. Parrot will print out each opcode and the parameters passed to it as it is called. This flag does not take any parameters.
PARROT_BOUNDS_FLAG
This flag turns on bounds checking. Parrot will make sure that all addresses returned by an opcode function are within the boundaries of the bytecode block. This flag does not take any parameters.
PARROT_PROFILE_FLAG
This flag turns on profiling. Parrot will print out a list of each opcode called, the number of times it was called, the average time it took to run, and the total time it took over the life of the program. This flag does not take any parameters.
PARROT_PREDEREF_FLAG
This flag turns on predereferencing. Parrot will transform many offsets in the opcode stream to absolute pointers. This flag does not take any parameters.
PARROT_JIT_FLAG
This flag turns on just-in-time compilation. Parrot will convert the bytecode file into native machine code and run it, usually resulting in substantial speedup. This flag does not take any parameters.
Other constants:
PARROT_VERSION
This constant contains a string representation of Parrot's version number.
PARROT_MAJOR_VERSION
This constant contains the first part of Parrot's version number.
PARROT_MINOR_VERSION
This constant contains the second part of Parrot's version number.
PARROT_PATCH_VERSION
This constant contains the third part of Parrot's version number.
PARROT_CONFIG_DATE
This constant contains the date that Configure was run to generate config.h.
PARROT_JIT_CAPABLE
This constant is true if Parrot supports JIT on this platform, false otherwise.
PARROT_ARCHNAME
This constant contains a string representation of the Parrot JIT's name for the current architecture.
PARROT_CPU_ARCH
This constant contains the name of your processor (as the JIT sees it).
PARROT_OS_NAME
This constant contains the name of your operating system (as the JIT sees it).
Parrot_Interp Parrot_new(Parrot_Interp parent)
Allocates and returns a new Parrot interpreter. parent is NULL for the main interpreter that will be destroyed last.
parent
void Parrot_init(Parrot_Interp)
Initializes a Parrot interpreter.
void Parrot_setflag(Parrot_Interp, Parrot_Interp_flag, Parrot_Interp_flag_val)
Sets a flag in the Parrot interpreter.
Parrot_PackFile Parrot_readbc(Parrot_Interp, char *filename)
Reads in a bytecode file and returns a packfile structure for it.
void Parrot_loadbc(Parrot_Interp, Parrot_PackFile)
Loads a packfile into a Parrot interpreter.
void Parrot_runcode(Parrot_Interp, int argc, char *argv[])
Runs the bytecode associated with a Parrot interpreter. argc and argv are the parameters the bytecode should receive.
argc
argv
Parrot_destroy(Parrot_Interp)
Deallocates all memory associated with a Parrot interpreter.
XXX At the moment, it just leaks most of it.
embed.c and embed.h for the implementation.
src/test_main.c for Parrot's use of the embedding system.
To install Make, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Make
CPAN shell
perl -MCPAN -e shell install Make
For more information on module installation, please visit the detailed CPAN module installation guide.