docs/embed.pod

   1 # Copyright (C) 2001-2008, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 embed.pod - Parrot embedding system
   7
   8 =head1 SYNOPSIS
   9
  10     #include <parrot.h>
  11     #include <parrot/embed.h>
  12     #include <parrot/extend.h>
  13
  14     int main(int argc, char* argv[])
  15     {
  16         Parrot_Interp interp;
  17         Parrot_PackFile pf;
  18
  19         interp = Parrot_new(NULL);
  20         if (!interp) {
  21             return 1;
  22         }
  23
  24         pf = Parrot_readbc(interp, "foo.pbc");
  25         Parrot_loadbc(interp, pf);
  26         Parrot_runcode(pf, argc, argv);
  27
  28         Parrot_destroy(interp);
  29
  30         return 0;
  31     }
  32
  33 =head1 FILES
  34
  35 =over 4
  36
  37 =item F<include/parrot.h>
  38
  39 =item F<include/parrot/embed.h>
  40
  41 =item F<include/parrot/extend.h>
  42
  43 =back
  44
  45 =head1 DESCRIPTION
  46
  47 This is the documentation for Parrot's embedding API.
  48
  49 =head2 Data structures
  50
  51 =over 4
  52
  53 =item C<Parrot_Interp>
  54
  55 The topmost data structure in Parrot is C<Parrot_Interp>, which represents
  56 a Parrot interpreter.  It is a required argument to almost every Parrot API
  57 function.  The structure is opaque in an embedded environment, so you cannot
  58 directly access any of its members.
  59
  60 =item C<Parrot_PackFile>
  61
  62 A Parrot packfile, the internal structure containing Parrot bytecode.
  63
  64 =item C<Parrot_String>
  65
  66 Parrot's internal string type, which contains character encoding information.
  67
  68 =item C<Parrot_PMC>
  69
  70 A Parrot Magic Cookie.  This is the opaque external type for (PMC *).  Note
  71 that this is a macro, so there can be only one C<Parrot_PMC> declaration per
  72 line.
  73
  74 =item C<Parrot_Int>
  75
  76 =item C<Parrot_Float>
  77
  78 =item C<Parrot_Int>
  79
  80 =item C<Parrot_UInt>
  81
  82 Parrot's numeric types.
  83
  84 =back
  85
  86 =head2 Constants
  87
  88 Not documented yet.
  89
  90 =head2 Type signatures
  91
  92 These are used with the Parrot_call_sub family of functions.
  93
  94 =over 4
  95
  96 =item v - void (return only)
  97
  98 =item I - integer (return or argument)
  99
 100 =item N - float (return or argument)
 101
 102 =item S - string (return or argument)
 103
 104 =item P - PMC (return or argument)
 105
 106 =back
 107
 108 =head2 Interpreter initialization and destruction
 109
 110 =over 4
 111
 112 =item C<Parrot_Interp Parrot_new(Parrot_Interp parent)>
 113
 114 Creates a new interpreter, inheriting some data structures from a parent
 115 interpreter, if supplied.  The first interpreter in any process should be
 116 created with a NULL parent, and all subsequent interpreters in the same
 117 process should use the first interpreter as their parent.  Failure to do so
 118 may result in unpredictable errors.
 119
 120 =item C<Parrot_set_flag(Parrot_Interp interp, Parrot_int flags)>
 121
 122 Sets or unsets interpreter flags.  Flags should be OR'd together.  Valid
 123 flags include:
 124
 125 =over 4
 126
 127 =item PARROT_NO_FLAGS
 128
 129 =item PARROT_BOUNDS_FLAG
 130
 131 =item PARROT_GC_DEBUG_FLAG
 132
 133 =item PARROT_EXTERN_CODE_FLAG
 134
 135 =item PARROT_DESTROY_FLAG
 136
 137 =item PARROT_IS_THREAD
 138
 139 =item PARROT_THR_COPY_INTERP
 140
 141 =item PARROT_THR_THREAD_POOL
 142
 143 =item PARROT_THR_TYPE_1
 144
 145 =item PARROT_THR_TYPE_2
 146
 147 =item PARROT_THR_TYPE_3
 148
 149 =back
 150
 151 See F<interpreter.h> for the definition of these flags (TODO: document flag
 152 definitions here).
 153
 154 =item C<void Parrot_set_run_core(Parrot_Interp interp, Parrot_Run_core_t core)>
 155
 156 Sets the runcore for the interpreter.  Must be called before executing any
 157 bytecode.  Valid runcores include:
 158
 159 =over 4
 160
 161 =item PARROT_SLOW_CORE
 162
 163 =item PARROT_FUNCTION_CORE
 164
 165 =item PARROT_FAST_CORE
 166
 167 =item PARROT_SWITCH_CORE
 168
 169 =item PARROT_CGP_CORE
 170
 171 =item PARROT_CGOTO_CORE
 172
 173 =item PARROT_JIT_CORE
 174
 175 =item PARROT_CGP_JIT_CORE
 176
 177 =item PARROT_SWITCH_JIT_CORE
 178
 179 =item PARROT_EXEC_CORE
 180
 181 =item PARROT_GC_DEBUG_CORE
 182
 183 =back
 184
 185 See F<interpreter.h> for the definitive list.  If you're not sure which runcore
 186 to use, don't call this function.  The default will be fine for most cases.
 187 (TODO: document runcores here).
 188
 189 =item C<Parrot_set_trace(Parrot_Interp, Parrot_UInt flags)>
 190
 191 Sets the interpreter's trace flags.  Flags should be OR'd together.  Valid
 192 flags are:
 193
 194 =over 4
 195
 196 =item PARROT_NO_TRACE
 197
 198 =item PARROT_TRACE_OPS_FLAG
 199
 200 =item PARROT_TRACE_FIND_METH_FLAG
 201
 202 =item PARROT_TRACE_SUB_CALL_FLAG
 203
 204 =item PARROT_ALL_TRACE_FLAGS
 205
 206 Z<>
 207
 208 =back
 209
 210 =item C<void Parrot_set_executable_name(Parrot_Interp interp, Parrot_string name)>
 211
 212 Sets the executable name of the calling process.  Note that the name is a
 213 Parrot string, not a C string.
 214
 215 =item C<void Parrot_destroy(Parrot_Interp interp)>
 216
 217 Destroys an interpreter.  At the time of this writing, this is a no-op.
 218 See <Parrot_really_destroy()>.
 219
 220 =item C<void Parrot_really_destroy(Parrot_Interp interp, int exit_code)>
 221
 222 Destroys an interpreter, regardless of the environment.  The exit code is
 223 currently unused.
 224
 225 =item C<void Parrot_exit(Parrot_Interp interp, int status)>
 226
 227 Destroys the interpreter and exits with an exit code of C<status>.  Before
 228 exiting, the function calls all registered exit handlers in LIFO order.
 229 C<Parrot_really_destroy()> is usually called as the last exit handler.
 230
 231 =item C<void Parrot_on_exit(Parrot_Interp interp,
 232                             void (*handler)(Parrot_Interp, int, void *), void *arg)>
 233
 234 Registers an exit handler to be called from C<Parrot_exit()> in LIFO order.
 235 The handler function should accept as arguments an interpreter, an integer
 236 exit code, and an argument (which can be NULL).
 237
 238 =item C<void imcc_init(Parrot_Interp interp)>
 239
 240 Initializes the IMCC subsystem.  Required for compiling PIR.
 241
 242 =back
 243
 244 =head2 Loading and running bytecode
 245
 246 =over 4
 247
 248 =item C<Parrot_PackFile Parrot_readbc(Parrot_Interp interp, const char *path)>
 249
 250 Reads Parrot bytecode or PIR from the file referenced by C<path>.  Returns
 251 a packfile structure for use by C<Parrot_loadbc()>.
 252
 253 =item C<void Parrot_loadbc(Parrot_Interp interp, Parrot_PackFile pf)>
 254
 255 Loads a packfile into the interpreter.  After this operation the interpreter
 256 is ready to run the bytecode in the packfile.
 257
 258 =item C<void Parrot_runcode(Parrot_Interp interp, int argc, char *argv[])>
 259
 260 Runs the bytecode associated with the interpreter.  Use C<argc> and C<argv[]>
 261 to pass arguments to the bytecode.
 262
 263 =item C<Parrot_PackFile PackFile_new_dummy(Parrot_Interp interp, char *name)>
 264
 265 Creates a "dummy" packfile in lieu of actually creating one from a bytecode
 266 file on disk.
 267
 268 =item C<void Parrot_load_bytecode(Parrot_Interp interp, const char *path)>
 269
 270 Reads and load Parrot bytecode or PIR from the file referenced by C<path>.
 271 You should create a dummy packfile beforehand; see C<PackFile_new_dummy> for
 272 details.  Due to the void return type, the behavior of this function on error
 273 is unclear.
 274
 275 =back
 276
 277 =head2 Data manipulation
 278
 279 =head3 Native types
 280
 281 =over 4
 282
 283 =item C<int Parrot_PMC_typenum(Parrot_Interp interp, const char *type)>
 284
 285 Returns the internal type number corresponding to C<type>.  Useful for
 286 instantiating various Parrot data types.
 287
 288 =item C<char *string_to_cstring(Parrot_Interp interp)>
 289
 290 XXX needs to be a formal Parrot_* API.
 291 Returns the C string representation of a Parrot string.
 292
 293 =item C<STRING *string_from_cstring(Parrot_Interp interp, const char *string, int len)>
 294
 295 XXX needs to be a formal Parrot_* API.
 296 Returns the Parrot string representation of a C string.
 297
 298 =item C<string_from_literal(Parrot_Interp interp, const char *string)>
 299
 300 XXX needs to be a formal Parrot_* API.
 301 A macro for simplifying calls to C<string_from_cstring>.
 302
 303 =back
 304
 305 =head3 PMCs
 306
 307 =over 4
 308
 309 =item C<Parrot_PMC Parrot_PMC_new(Parrot_Interp interp, int typenum)>
 310
 311 Creates a new PMC of the type identified by C<typenum>.  Use
 312 C<Parrot_PMC_typenum> to obtain the correct type number.
 313
 314 =item C<void Parrot_register_pmc(Parrot_PMC pmc)>
 315
 316 Registers an externally created PMC with the garbage collector.  You MUST call
 317 this for any PMCs you create outside of Parrot bytecode, otherwise your PMC
 318 may be garbage collected before you are finished using it.
 319
 320 =item C<void Parrot_unregister_pmc(Parrot_PMC pmc)>
 321
 322 Unegisters an externally created PMC from the garbage collector.  You MUST call
 323 this after you are finished using PMCs you create outside of Parrot bytecode,
 324 or risk memory leaks.
 325
 326 =back
 327
 328 =head3 Globals
 329
 330 =over 4
 331
 332 =item C<Parrot_PMC Parrot_find_global_cur(Parrot_Interp interp, Parrot_String name)>
 333
 334 Find and return a global called C<name> in the current namespace.  Returns
 335 C<PMCNULL> if not found.
 336
 337 =item C<Parrot_PMC Parrot_find_global_n(Parrot_Interp interp, Parrot_String namespace, Parrot_String name)>
 338
 339 Not documented yet.
 340
 341 =item C<Parrot_PMC Parrot_find_global_s(Parrot_Interp interp, Parrot_String namespace, Parrot_String name)>
 342
 343 Find and return a global called C<name> in the namespace C<namespace>.  Returns
 344 C<PMCNULL> if not found.
 345
 346 =item C<void Parrot_store_global_cur(Parrot_Interp interp, Parrot_String name, Parrot_PMC val)>
 347
 348 Sets the value of a global called C<name> in the current namespace.  Does
 349 nothing if the global is not found.
 350
 351 =item C<void Parrot_store_global_n(Parrot_Interp interp, Parrot_String namespace, Parrot_String name, Parrot_PMC val)>
 352
 353 Not documented yet.
 354
 355 =item C<void Parrot_store_global_s(Parrot_Interp interp, Parrot_String namespace, Parrot_String name, Parrot_PMC val)>
 356
 357 Sets the value of a global called C<name> in the namespace C<namespace>.  Does
 358 nothing if the global is not found.
 359
 360 =item C<Parrot_PMC Parrot_find_global_k(Parrot_Interp interp, Parrot_PMC namespace_key, Parrot_String name)>
 361
 362 Find and return a global called C<name> in the keyed namespace C<namespace>.
 363 Returns C<PMCNULL> if not found.
 364
 365 =item C<void Parrot_store_global_k(Parrot_Interp interp, Parrot_PMC namespace_key, Parrot_String name, Parrot_PMC val)>
 366
 367 Sets the value of a global called C<name> in the keyed namespace C<namespace>.
 368 Does nothing if the global is not found.
 369
 370 =back
 371
 372 =head3 Lexicals
 373
 374 Not documented yet.
 375
 376 =head2 Calling subroutines
 377
 378 =over 4
 379
 380 =item C<void *Parrot_call_sub(Parrot_Interp interp, Parrot_PMC sub, const_char *signature)>
 381
 382 Call a Parrot subroutine that returns a pointer using the supplied signature.
 383
 384 =item C<Parrot_Int Parrot_call_sub_ret_int(Parrot_Interp interp, Parrot_PMC sub, const_char *signature)>
 385
 386 Call a Parrot subroutine that returns an integer using the supplied signature.
 387
 388 =item C<Parrot_Float Parrot_call_sub_ret_float(Parrot_Interp interp, Parrot_PMC sub, const_char *signature)>
 389
 390 Call a Parrot subroutine that returns an float using the supplied signature.
 391
 392 =back
 393
 394 =head2 Objects
 395
 396 =head3 Creating and destroying objects
 397
 398 =over 4
 399
 400 =item C<Parrot_PMC Parrot_oo_get_class(Parrot_Interp interp, Parrot_PMC namespace)>
 401
 402 Returns the class corresponding to the supplied namespace.
 403
 404 =item C<Parrot_PMC Parrot_Class_instantiate(Parrot_Interp interp, Parrot_PMC the_class Parrot_PMC arg)>
 405
 406 Instantiates a new object of class C<the_class>, which can be obtained from
 407 C<Parrot_oo_get_class()>.  Passes an optional PMC argument C<arg> to the
 408 constructor (see init versus init_pmc).  Use C<PMCNULL> if you are not
 409 supplying an argument.
 410
 411 =back
 412
 413 =head3 Calling methods
 414
 415 Not documented yet.
 416
 417 =head1 COMPILING
 418
 419 Note: This section is aimed at you if you are writing an application
 420 external to parrot which links against an installed parrot library.
 421
 422 =head2 Caveats
 423
 424 Several API functions are missing prototypes in Parrot's header files.  This
 425 means you may receive type warnings during compilation even though the types
 426 of your arguments and return variables are correct.  In this case it is safe
 427 to cast to the correct type; not doing so may cause undesired behavior.
 428
 429 =head2 Compiler and linker flags
 430
 431 Your application will need to include the appropriate header files and
 432 link against parrot and its dependencies.
 433
 434 Because the location of these files can vary from platform to platform, and
 435 build to build, a general method is provided to find out the necessary flags to
 436 use.
 437
 438 pkg-config is a helper tool, now common on many platforms, which many packages
 439 have adopted to provide the necessary compiler and linker flags required to
 440 build against a library. parrot will install a file called F<parrot.pc> which
 441 can be queried using pkg-config.
 442
 443 To start with, find out what version of parrot is installed by running
 444 pkg-config with the C<--modversion> flag. If this command fails with an error,
 445 skip to the end of this section.
 446
 447   pkg-config --modversion parrot
 448
 449 To find out the necessary C<-I> flags, use C<--cflags>:
 450
 451   pkg-config --cflags parrot
 452
 453 ... and to find the necessary C<-L> and C<-l> flags, use C<--libs>:
 454
 455   pkg-config --libs parrot
 456
 457 Where both compiling and linking are performed in one step, query both sets of
 458 flags with:
 459
 460   pkg-config --cflags --libs parrot
 461
 462 The pkg-config command can be incorporated with a compile as shown here.
 463
 464   cc src/disassemble.c `pkg-config --cflags --libs parrot`
 465
 466 Most applications will probably choose to run pkg-config as part of a
 467 configure script, so if you are using autoconf you could use a test
 468 such as this.
 469
 470   PARROT_REQUIRED_VERSION=0.4.1
 471   AC_SUBST(PARROT_REQUIRED_VERSION)
 472   PKG_CHECK_MODULES(PARROT, parrot >= $PARROT_REQUIRED_VERSION,
 473                     [AC_DEFINE([HAVE_PARROT], 1, [define if have parrot])])
 474   AC_SUBST(PARROT_LIBS)
 475   AC_SUBST(PARROT_CFLAGS)
 476
 477 If parrot has been installed system-wide, then any of the previous
 478 lines should have returned the relevant flags. If it is not installed
 479 in one of the standard places that pkg-config looks, then you will get
 480 an error message.
 481
 482   pkg-config --libs parrot
 483   Package parrot was not found in the pkg-config search path.
 484   Perhaps you should add the directory containing `parrot.pc'
 485   to the PKG_CONFIG_PATH environment variable
 486   No package 'parrot' found
 487
 488 As stated in the error message, use an environment variable to make pkg-config
 489 look in more locations.
 490
 491   export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 492
 493 The last part of the variable will almost certainly be F<.../lib/pkgconfig>.
 494 Set this variable in your login scripts if you need it to be available in
 495 future.
 496
 497 =head1 EXAMPLES
 498
 499 =head2 Load bytecode as a library and run a single subroutine
 500
 501     #include <parrot/parrot.h>
 502     #include <parrot/embed.h>
 503     #include <parrot/extend.h>
 504
 505     int main(int argc, char *argv[])
 506     {
 507         Parrot_Interp interp;
 508         Parrot_PackFile pf;
 509         Parrot_PMC sub;
 510         Parrot_String pstr;
 511
 512         interp = Parrot_new(NULL);
 513         imcc_init(interp);
 514
 515         /* create a new packfile -- any name will do */
 516         pf = PackFile_new_dummy(interp, "my-parrot-code");
 517
 518         pstr = string_from_literal(interp, "foo.pir");
 519         Parrot_load_bytecode(interp, pstr);
 520
 521         /* find the subroutine named "foo" in the global namespace */
 522         pstr = string_from_literal(interp, "foo");
 523         sub = Parrot_find_global_cur(interp, pstr);
 524
 525         /* run foo(), which returns nothing */
 526         Parrot_call_sub(interp, sub, "v");
 527
 528         Parrot_destroy(interp);
 529
 530         return(0);
 531     }
 532
 533 =head1 SEE ALSO
 534
 535 F<src/main.c> and F<t/src/*.t> for Parrot's use of the embedding system.
 536
 537 L<http://pkgconfig.freedesktop.org/wiki/> A pkg-config page
 538
 539 =cut